[Freeipa-devel] [PATCH] Make 'ipa help' localizable.

[John Dennis]

On 02/01/2011 08:16 AM, Pavel Zuna wrote:
> For a long time, I was trying to find a way to localize python docstrings, that
> we use to generate the built-in documentation system. Unfortunately, python
> docstrings aren't meant to be localized and therefore I had to use a dirty
> trick: setting the __doc__ variable manually to a gettext instance.
>
> There is one major disadvantage: tools that generate developer documentation
> (like epydoc) won't display docstrings set like this.
>
> One solution would be to have docstrings twice in each module: once normally and
> once set using __doc__, but that would be very ugly.
>
> This patch doesn't update .po files, because it's already big as it is. They are
> regenerated automatically anyway.
>
> Ticket #179
>
> Pavel

Hi Pavel:

I'm not sure this is the right approach. What we really want is to be 
able to extract the docstrings and put them in a pot file. Normally 
xgettext is used to "xtract" translatable strings but I don't think the 
python parser in xgettext is docstring aware (we should probably confirm 
that).

However pygettext in the python-tools package is docstring aware. From 
it's help text:

-D
--docstrings
     Extract module, class, method, and function docstrings.  These do
     not need to be wrapped in _() markers, and in fact cannot be for
     Python to consider them docstrings. (See also the -X option).

So rather than changing all the source code and making it non-standard I 
think we're better off using a more appropriate tool when building the 
pot file.

Use of pygettext is discussed and documented in this Python 
documentation link:

http://docs.python.org/library/gettext.html#internationalizing-your-programs-and-modules

You can find an interesting discussion of the docstring extraction issue 
in this thread:

http://mail.python.org/pipermail/i18n-sig/2001-August/001292.html

BTW, Barry Warsaw is the man behind Mailman and is one of the Python 
community luminaries.


-- 
John Dennis <jdennis at redhat.com>

Looking to carve out IT costs?
www.redhat.com/carveoutcosts/