[I18n-sig] Re: Patch 101320: doc strings

[Martin von Loewis]

> > > My feeling is that we should not rely on `_'.  The variable used to hold
> > > the translating function should be left at the discretion of the user.
> 
> > Well, what else do you propose?
> 
> Nothing special.  I suggest that we systematically use `_' in the
> documentation and examples, but that we also avoid forcing the issue in
> any way from within Python.  Let's use a function in `locale', say, to
> get a Translations instance (say) given the textual domain.  The language
> to use could be obtained from environment variables as well as the search
> path for the MO file, unless such things get overridden by keyword
> arguments.

That is indeed how the gettext.py API works: given a textual domain,
you get a Translations instance, considering environment variables.

The question is still how *doc* strings get translated, from outside
the module. I.e. the help() function needs to determine what textual
domain it is supposed to use when accessing the doc string of some
object. Presence of any function expecting a textual domain does no
good, as help() needs to find out what the textual domain is first.

> You ask the `locale' module to return you a Translations instance for
> that module, maybe though another keyword argument stating the name of
> the module for which you need a translator.  This would only work if that
> module previously registered its domain name, through asking the creation
> of a Translations instance for itself (and without specifying the keyword
> argument specifying a module, or course).

I see. I doubt that *not* specifying the module name gives is
acceptable, though - that locale function would need to know who its
caller is. I feel doing that is too hacky to be accepted for the
standard library.

> > So you propose that there be some kind of protocol to be observed by a
> > module that wants to make "its" textual domain known. What is that
> > protocol?
> 
> Maybe, I do not know, something like:
> 
>    _ = locale.translator(TEXTUAL_DOMAIN)
> 
> after the overall doc string for the module, for each module?  

I believe this would rather become

_ = locale.translator(TEXTUAL_DOMAIN, module = __name__)

for the reason mentioned above. But yes, that might work. It would
invalidate (or, rather, not support) prior art for binding _,
though. Traditionally, Python programs do (in GNOME specifically)

_ = gettext.gettext

With Barry's API, you do

gettext.install(TEXTUAL_DOMAIN)

which puts _ into __builtins__, so individual modules won't even bind
_ themselves.

> CWRI never confessed its true reasons, but now, we can tell it.  If they
> made all that legalese noise and stuff, that was only a circumvoluted way
> to buy us more time for completing internationalisation specifications. :-)

:-)

> But it gets frustrating for translators, at times.  I remember the long
> years it took before `make' translations could start to work

That's why I want to get some assurance that translations will be
indeed used when done. I'd like to get some agreement on procedures
among all interested people here, and I'd like to get some go-ahead
from BeOpen that they'll consider including it when it's done.

In any case, I'll push that Python distributors and packagers (RedHat,
Debian, ActiveState, ...) to include available catalogs even before they
get into an official distribution. As they are plain data files and
don't harm functionality, it's just a matter of file size to use them
or to leave them.

I also hope that the help module takes off, so that there is some
convenient way to access the doc string translations.

> If we can get Python itself to be internationalised within a year, say,
> it would be good publishing its POT file now.  But Python may also be seen
> as a package among others.  Python could offer internationalisation methods
> for Python scripts, without being immediately internationalised itself.

That is certain. I believe Python 2 will be well-equipped already,
having a gettext module, and xgettext and msgfmt utilities in 100%
pure Python. For a full i18n process, only a msgmerge utility and a
po-mode editor (in Tk?) would be missing. Of course, on many systems,
GNU equivalents of these tools will be available now.

Regards,
Martin