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

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 13, 2017, 00:01 UTC
Message-ID: <xmqq1su2ujsf.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20170312200248.3610-2-jn.avila@free.fr>

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

Show 23 quoted lines

> +#. 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.

Show 13 quoted lines

> +#. 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?

Show 23 quoted lines

> +#. 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.