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

Bruno Haible haible@ilog.fr
Tue, 14 Aug 2001 22:51:50 +0200 (CEST)

Martin v. Loewis writes:
> people writing programs in Python not
> necessarily read fluently English ... Likewise, the French
> translation of the Python documentation was started precisely because
> users don't read English that well.

OK, let me formulate it less strictly: Programmer's documentation is
usually translated to much fewer languages (Japanese, French and very
few others), because the amount of text to translate is quite large
and the translator must have programmer's know-how.

> Many Python applications present
> docstrings to the user, instead of using them for documentation, by
> means of accessing some object's __doc__ attribute at
> runtime. E.g. you might have a drop-down menu, each item invoking a
> different function. Then somebody might chose to key the online help
> into the docstring. It is somewhat hackish, but common.

It is pure Lisp introspection tradition :-) But nevertheless, it
presents a problem: How can the translator know which docstrings are
important to translate for the end user, and which are not?

The danger is that a translator for Finnish, Turkish or Romanian,
without deep programming knowledge, will spend a lot of his time
translating programmer's documentation, which won't help the end users
of his country. There are not many translators for these languages; we
shouldn't abuse them.

IMO, those __doc__ strings that are used at runtime should be
explicitly marked as translatable by the programmer, to avoid excess
work by the translator. The way you mark them doesn't really matter; it
can be a tag in a comment, or something else that triggers xgettext

> It turns out that there is a "batteries included" issue here. I know a
> few cases where people have been using pygettext just because it was
> already on their (Windows) system, whereas GNU gettext was not that
> readily available (you'd need a C compiler to build it).

You can point these people to the http://gnuwin32.sourceforge.net/
site which has gettext binaries for Win32 ready for download.