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

[François Pinard]

[Martin von Loewis]

> Me:    I propose a single domain for docstrings, 'pylib'.
> Barry: This is too large, split it up.
> Me:    Then how do you access the individual strings?
> Barry: Use the module name.
> Me:    This will give too many domains.
> Barry: There might be some point in having a /docstring/ domain [for
>        the python library]

Oh, oh!  So, I see that Barry is the bad guy, after all? :-)

> I did not propose a *separate* domain for doc strings. I proposed that
> there is one well-known domain in which the doc strings of the core
> python library can be found.  I don't care too much at this time whether
> it contains anything else - there are no other translatable strings in
> the Python sources at this point in time.

OK, then, let's call it "python", and if other strings are needed from
the Python distribution, let's also use that "python" domain for it as
well for them.  Very fine with me! :-)

> > 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.

> > Why not just use the textual domain of a module, to translate the doc
> > strings it contains?

> How do I find out the textual domain of a module? How do I find out
> the module of a builtin function?

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).

> 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?  For all modules
being part of the Python distribution, it would be:

   _ = locale.translator("python")

Of course, if a module does not need to translate any string explicitely,
a mere:

   locale.translator("python")

would be sufficient, in which case the `_' variable gets undisturbed,
of course.

The `locale.translator' function would call `locale.Translator()' if it
finds that none exist yet for the textual domain "python" and the specified
language sequence (which could be specified by keyword, but defaulting to
LANGUAGE in the environment, or else LANG, or none).

> I also propose a protocol: A module can announce its textual domain by
> binding _.  It may chose not to bind _, or it may chose not to bind it
> to a catalog method.  In either case, it does not follow the protocol,
> so anybody using that protocol may get some kind of failure.

I understand, but I think we may avoid imposing `_'.  Even if we expect
it to be popular, best is to not rely on it, if we can avoid doing it.

> - Did you agree that doc strings of a module should use the same
>   domain as all other strings of the module?

Sounds good to me.

> - Did you propose that a single package, distributed as a whole,
>   should have a single textual domain?

As far as possible, yes.  It seems to be the good thing to do for most
things so far.  This is not an absolute, of course, but we should not
start with the idea that splitting is necessary.  If we later discover
some exceptional property or condition that makes a sounded and solid
justification for it, it would be worth exploring, but so far that I know
(and given I've not read all my mail yet :-), none shown up yet.  If we
have many tens of thousands of doc strings, it might change the balance,
I do not know.

> - Do you agree that the Python core+libs is a single package?

I'm tempted to much agree, yes.

> From that, I'd conclude that you are in favour of having a single
> domain for the Python core+libs, which contains both doc strings
> and other translatable strings of Python core+libs.

Yes, of course.

But we cannot blindly rely that the textual domain for any module is
"python", as a Python relies on the run-time importation of many scripts from
various sources.  A good deal of modules will have "python" to start with,
but modules could be added or overridden: the textual domain of a module
should be registered by that module, and retrieved whenever appropriate.

> I've given up on having message catalogs in the Python 2.0
> distribution.

Do not loose hope yet.  Who knows what will happen! :-)

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. :-)

> What *is* urgent is to give the catalog to the translators.

This, I deeply understand!  The big work is mainly done by translators,
and PO files are re-usable even when the API changes or fluctuates, or
is postponed.  So, the translation effort is usually best invested.

But it gets frustrating for translators, at times.  I remember the long
years it took before `make' translations could start to work, for example.
`bison' was not immediate either.  And even now, `diffutils' and `bash'
are not settled, while translations for those existed for years.  I thought
that the `tar'/`cpio' saga was over, but it seems it has to be restarted,
for reasons some of you might know :-).

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.

-- 
François Pinard   http://www.iro.umontreal.ca/~pinard