[I18n-sig] Re: pygettext.py extraction of docstrings

[Bruno Haible]

Barry A. Warsaw writes:
> A while back I was convinced to switch the `docstring' flag to #, for
> pygettext. ... It probably only has
> meaning in Python, but may be useful in other scripting languages.
> Think of it roughly equivalent to Emacs-Lisp docstrings (in fact,
> they were the inspiration for Python docstrings back in '94 at the
> 1st Python workshop!)

Well, Common Lisp has had docstrings long before Emacs-Lisp and
Python. Their purpose is to have documentation available for the
programmer, in a running session, regardless where each class or
function came from.

Now, why do you want to translate them?

As gettext maintainer, I'm used to think in the categories of
programmer - translator - user. Translated docstrings are not for the
users, because users are not programmers in general. And the
programmers (of .py programs), who must have looked at the various
Python manuals, certainly reads English.

So, as I see it,

  - translated docstrings have a much smaller audience than
    usual translated messages,

  - tranalated docstring users could also use the untranslated
    English docstrings,

  - docstrings are harder to translate, because the translator
    needs to have programmer's know-how.

Therefore I think that docstring translation is a separate process
than usual translations, and should use different .po files.

As a consequence for gettext, I could live with an xgettext option
--docstrings which extracts *only* the docstrings of a set of source
files.

> Perhaps Bruno can add some information on pygettext.py in
> the GNU gettext manual?

The GNU gettext tools are currently being modified to handle various
programming languages. A new flag 'python-format' is being
introduced, with appropriate format string checking in 'msgfmt'.
xgettext will also have a Python backend, making pygettext obsolete
(except for docstring extraction, for the time being).

Bruno