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

[Junio C Hamano <gitster@pobox.com>]

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

> +#. type: Title =
> +#: git-add.txt:2
> +#, no-wrap
> +msgid "git-add(1)"
> +msgstr "git-add(1)"
> +
> +#. type: Title -
> +#: git-add.txt:5
> +#, no-wrap
> +msgid "NAME"
> +msgstr "NOM"
> +
> +#
> +#. type: Plain text
> +#: git-add.txt:7
> +msgid "git-add - Add file contents to the index"
> +msgstr "git-add - Ajoute le contenu de fichiers à l'index"
> +
> +#. type: Title -
> +#: git-add.txt:9
> +#, no-wrap
> +msgid "SYNOPSIS"
> +msgstr "SYNOPSIS"

It is a wonderful goal to make localized manpages and corresponding
HTMLized documents available, and the above might look reasonable,
but other parts of what the translaters need to do we see below
makes me wonder if this is a sensible approach.

> +#. type: Plain text
> +#: git-add.txt:15
> +#, no-wrap
> +msgid ""
> +"'git add' [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]\n"
> +"\t  [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]]\n"
> +"\t  [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing]\n"
> +"\t  [--chmod=(+|-)x] [--] [<pathspec>...]\n"
> +msgstr ""
> +"'git add' [-n] [-v] [--force | -f] [--interactive | -i] [--patch | -p]\n"
> +"\t  [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]]\n"
> +"\t  [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing]\n"
> +"\t  [--] [<chemin>...]\n"

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?

> +#. type: Title -
> +#: git-add.txt:17
> +#, no-wrap
> +msgid "DESCRIPTION"
> +msgstr "DESCRIPTION"
> +
> +#
> +#. type: Plain text
> +#: git-add.txt:24
> +msgid ""
> +"This command updates the index using the current content found in the "
> +"working tree, to prepare the content staged for the next commit.  It "
> +"typically adds the current content of existing paths as a whole, but with "
> +"some options it can also be used to add content with only part of the "
> +"changes made to the working tree files applied, or remove paths that do not "
> +"exist in the working tree anymore."
> +msgstr ""
> +"Cette commande met à jour l'index en utilisant le contenu actuel trouvé dans "
> +"la copie de travail, pour préparer le contenu de la prochaine validation. "
> +"Typiquement, elle ajoute intégralement le contenu actuel des chemins "
> +"existant, mais peut aussi n'ajouter que certaines parties des modifications "
> +"au moyen d'options ou soustraire certains chemins qui n'existent plus dans "
> +"la copie de travail."

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.

Thanks.