[I18n-sig] Translating doc strings

[Martin v. Loewis]

Now that Python 2 supports the gettext API and methodology, I'd like
to start discussion on translating messages in the Python core and
library proper.

I see two different kinds of messages in the Python source: Printed
messages, which are produced in the course of running the interpreter
(including, say, informative parameters to exceptions), and doc
strings (which are not normally printed during program execution, but
are instead retrieved by a developer.

I have produced patch 101320, which is available from

http://sourceforge.net/patch/?func=detailpatch&patch_id=101320&group_id=5470

The patch consists of a message catalog for Python doc strings,
beginnings of a German translation thereof, a compiled version of the
German catalog, and makefile machinery to install the catalogs.

When discussing this patch with BeOpen, Barry and Guido raised
concerns about the size of the catalog; Barry proposed to split it
into pieces.

Splitting the patch into pieces has its own problems: How to split,
and should the pieces become their own textual domains?

How would users retrieve translations of the doc strings in the first
place? I have proposed patch 101313

http://sourceforge.net/patch/?func=detailpatch&patch_id=101313&group_id=5470

which introduces a doc() function, so that users could write

>>> doc("".split)
S.split([sep [,maxsplit]]) -> Liste von Strings

Gib eine Liste der Worte im String S zurück, mit sep als Trennstring.
Wenn maxsplit angegeben ist, werden höchstens maxsplit Worte
abgetrennt.  Wenn sep nicht angegeben ist, gelten beliebige
Whitespace-Strings als Trenner.

This interface has a number of advantages:
- you don't have to type print in the front to get line breaks display
  properly
- you don't have to type _ four times
- it will transparently retrieve the translation if available

For this to work, all doc strings must be in a single textual
domain. The implementation of the doc function will retrieve the
__doc__ attribute of the argument and look for a translation.

With that approach, the next question is: What is the name of the
textual domain, and how are translation managed? My proposal was
"pylib"; Barry's "docstring". As for management of translations, I'd
like to ask the Free Translation Project for help. As soon as we've
settled the technical issues, I'd like to submit a catalog for
translation.

Comments?

Martin