Subject: Re: [PATCH v2 1/2] l10n: Introduce framework for localizing man pages

From: Jean-Noël AVILA <[email-masked]>
Date: Sat, 18 Mar 2017 23:17:10 +0100

Le samedi 18 mars 2017, 12:41:22 CET Junio C Hamano a écrit :
> Jean-Noel Avila <[email-masked]> writes:
> > Providing git in localized version is a good step for general adoption
> > of the tool. But as of now, if one needs to refer to the manual pages,
> > they are still confronted to english. The aim is to provide
> > documentation to users in their own language.
> 
> Please outline how the end result looks like here.  Where are the
> localized man pages installed?  Do installers get to choose to build
> and install the localization for some but not all languages and if
> so how?  etc.
> 
> > signed-off-by: Jean-Noel Avila <[email-masked]>
> 
> s/sign/Sign/;
> 
> > -man: man1 man5 man7
> > +man: man1 man5 man7 man_l10n
> 
> Hmmm, at least in the early days of the topic, I'd prefer that "make
> doc" and "make install" I need to run dozens of times a day from the
> toplevel not to require po4a.
> 
> Thanks.

Fair enough. 

Anyway, now I see  there's a take away from the discussion thread. Right now 
the man pages are tagged with the actual version of git, because the 
documentation is supposed to change at the same pace as the code. But that may 
not be true for translations, In this case, the automatic running of po4a will 
generate fuzzy matches which are not going to be used in the translated texts, 
leading to patchworked manpages, depending on the level of acceptance of 
untranslated entities.

If we want to freeze the translated manpages at a given version of git until a 
new version of the manpages is fully translated, we'll have to commit the 
translated .txt and force in some way the version to freeze (not using the 
generic asciidoc target of the Makefile).  But, that may drag the version of 
translations far behind the original if translation is stalled.

Or maybe people will not be so upset by mixed language manpages when the 
translation is lagging, but will prefer to have a "best available translation" 
of up-to-date pages. Plus that would be managed automatically by po4a's level 
of translation threshold to effectively generate a translated man page as long 
as the untranslated parts are still sparse in the mixed-up text.

For now, I keep this last option.