Re: [PATCH] l10n: add framework for localizing the manpages

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Mar 14, 2017, 21:00 UTC
Message-ID: <CACBZZX4EGfBAu0M0y4xboVAtWf5N07XY8s40npQ1hN3rbgqmSw@mail.gmail.com>
In-Reply-To: <xmqq1su2ujsf.fsf@gitster.mtv.corp.google.com>

On Mon, Mar 13, 2017 at 1:01 AM, Junio C Hamano <gitster@pobox.com> wrote:

> Jean-Noel Avila <jn.avila@free.fr> writes:

Jean: Comments on the patch:

- Firstly thanks for working on this. When I hacked up the initial po
support in v1.7.8-rc2-1-g5e9637c629 I always meant to try out po4a,
but never got around to it. It's much easier than I thought.
- Consider submitting a more minimal patch that doesn't have the giant
fr.po (or just some minor cut version) as the tip of the series, to
make this easier to review
- The git-add.txt file is hardcoded in po4a.conf, won't this file need
to be generated in some final version of this series?

Show 33 quoted lines

> This shows that even after adding just _one_ new option to the
> command, the whole thing need to be re-translated (the SYNOPSIS
> section may be a bad example, as not much is subject to i18n,
> though).  If each paragraph of the description section becomes a
> single string that need to be re-translated, as we can see below, I
> am not sure if it really helps the translators.  A mere single
> rephrasing of a word in a large paragraph would have to result in
> the entire paragraph to be translated again?
>
> [...]
>
> It almost makes me suggest that a totally different approach might
> be more manageable.  For example, we can pick one version of a
> source file (say, "v2.12.0:Documentation/git-add.txt"), have it
> fully translated to the target languages, _and_ make it a convention
> to record the original blob object name at the end of the translated
> file.  Perhaps "Documentation/l10n/fr/git-add.txt" may record the
> result of such translation effort.
>
> And then, when somebody wants to update the translation for v2.13.0,
> perhaps
>
>     git diff --color-words $old_blob v2.13.0:Documentation/git-add.txt
>
> (where $old_blob is taken from Documentation/l10n/fr/git-add.txt)
> can be examined and then Documentation/l10n/fr/git-add.txt can be
> adjusted to match the changes between the two versions.  After that,
> update the "source" blob object name in the translation.
>
> So, I dunno.  I like the goal and appreciate the effort to get to
> that goal.  I am not sure what the best approach would be and the
> sample translation mechanism I see in this patch makes me doubt that
> it is the best approach.

Junio: The concerns about long strings being altered & needing to be
translated is something already addressed by the gettext toolchain.
Your existing translations turn "fuzzy", and you can see a
before/after version of what changed in popular tools.

The proposal to do something like "git diff --words" is suboptimal because it just gives you the same things these gettext tools give you, but more importantly even though it's pretty feature similar in theory you lose the advantage of plug-in integration with any arbitrary gettext tool, e.g. the transifex or weblate tools Jean mentioned.

Also, having done a lot of translations myself (although not for Git, just the translation infra), it's a huge advantage to be able to partially translate certain things out of order (e.g. parts of git-add.txt), and even have different people do different parts. This is trivial and you get out of the box support for it with the gettext tooling, but not if we just have git-add.txt translated in its entirety to e.g. French & record what the blob sha1 was.

I think this series is on the right track, and that po4a is the right tool for the job.