[Freeipa-devel] [PATCH 46/46] ticket 1669 - improve i18n docstring extraction

[Alexander Bokovoy]

On 25.08.2011 06:46, John Dennis wrote:
> class foo(Command):
>     '''
>     The foo command takes out the garbage.
>     '''
> 
> Would become:
> 
> class foo(Command):
>     __doc__ = _('The foo command takes out the garbage.')
> 
> But which docstrings need to be marked for translation? The makeapi
> tool knows how to iterate over every command in our public API. It was
> extended to validate every command's documentation and report if any
> documentation is missing or not marked for translation. That
> information was then used to identify each docstring in the code which
> needed to be transformed.
Read through whole patch. This is one of rare cases where gettext's use
of original text as translation id isn't helpful from both performance
(longer calculation of Id hash during run-time) and maintenance. Looks
like we have to live with that if Transifex is unable to work with
indirected translation ids -- that would mean authoritative original
text would be in 'en' translation, not as original translation id.

If that can't be solved, I'm fine with this approach.
> In summary what this patch does is:
> 
> * Remove the use of pygettext (modification to install/po/Makefile.in)
ACK

> * Replace every docstring with an explicit assignment to __doc__ where
>   the rhs of the assignment is an i18n marking function.
ACK

> * Single line docstrings appearing in multi-line string literals
>   (e.g. ''' or """) were replaced with single line string literals
>   because the multi-line literals were introducing unnecessary
>   whitespace and newlines in the string extracted for translation. For
>   example:
ACK

> * Import statements were moved from below the docstring to above
>   it. This was necessary because the i18n markers are imported
>   functions and must be available before the the doc is
>   parsed. Technically only the import of the i18n markers had to
>   appear before the doc but stylistically it's better to keep all the
>   imports together.
ACK

> * It was observed during the docstring editing process that the
>   command documentation was inconsistent with respect to the use of
>   periods to terminate a sentence. Some doc had a trailing period,
>   others didn't. Consistency was enforced by adding a period to end of
>   every docstring if one was missing.
ACK.

-- 
/ Alexander Bokovoy