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

[Rob Crittenden]

Alexander Bokovoy wrote:
> 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.
>

ACK from me too, pushed to master and ipa-2-1

I discovered some issues with the Spanish translation while testing this 
and opened a ticket to investigate. It isn't related to these changes.

rob