Re: [PATCH v2 9/9] l10n: Document the new l10n workflow

From: Junio C Hamano <gitster@pobox.com>
Date: May 19, 2022, 17:18 UTC
Message-ID: <xmqqfsl5phjw.fsf@gitster.g>
In-Reply-To: <20220519081548.3380-10-worldhello.net@gmail.com>

Jiang Xin <worldhello.net@gmail.com> writes:

> +## Creating the "po/git.pot" file
> +
> +The "po/git.pot" file, once generated by the the l10n coordinator had

"once generated" -> "used to be generated"

> +been removed from the tree. L10n contributors can generated it at

"can generated it" -> "can generate it"

Show 5 quoted lines

> +runtime using command:
> +
> +```shell
> +make pot
> +```

Just a minor detail, but I wonder if we want "make po/git.pot" here rather than "make pot", as the text before this command talks about "creating the po/git.pot file". It used to be that the readers of this document didn't have to worry about po/git.pot and the only thing they needed to know was stuff starting from "make po-init", but now they must be more aware of po/git.pot than before, so...

> +Then language contributors use this file to prepare translations for
> +their language, but they are not expected to modify it.

Show 8 quoted lines

> @@ -115,32 +117,14 @@ If your language XX does not have translated message file "po/XX.po" yet,
> ...
> +make po-init PO_FILE=po/XX.po
>  ```
>  
> -And change references to PACKAGE VERSION in the PO Header Entry to
> -just "Git":
> +Where XX is the locale, e.g. "de", "is", "pt\_BR", "zh\_CN", etc.

"Where" -> "where".

XX was called "the two character language translation codes" (mouthful isn't it) in much earlier part of the documentation, but here it stands for more than the language part. I wonder if that is confusing and we'd better use something other than XX.

In any case, we should define "locale" and tell the readers that language "XX" can be followed by territory "_YY" that clarifies the variant of the language, probably at the same place where we explained the two-letter language code and to the same degree by explaining the two-letter country codes and where they come from (i.e. ISO 3166-1).

> +It will:
>  
> +- Call "make pot" at runtime to generate new "po/git.pot" file

What does "at runtime" mean here? Would it change the meaning if I rewrote this line to

	Call "make pot" to generate new "po/git.pot" file

at all? To put it differently, does it call "make pot" at runtime, but it does not call "msgmerge --add-location ..." at runtime?

If "at runtime" is truly a noiseword, then remove it. It is confusing.

Show 5 quoted lines

> +- Call "msgmerge --add-location --backup=off -U po/XX.po po/git.pot"
> +  to update your "po/XX.po"
> +- The "--add-location" option for msgmerge will add location lines,
> +  and these location lines will help translation tools to location
> +  translation context easily.

"help translation tools to location" -> "help translation tools to locate"

probably.

Show 9 quoted lines

> +To save a location-less "po/XX.po" automatically in repository, you
> +can:
> +
> +- Define new attribute for "po/XX.po" by adding new line in
> +  ".git/info/attributes":
> +
> +        /po/XX.po filter=gettext-no-location
> +
> +- Define driver for "gettext-no-location" filter:

"filter" -> "clean filter"?

> +        $ git config --global filter.gettext-no-location.clean \
> +              "msgcat --no-location -"
> +
> +You're now ready to ask the l10n coordinator to pull from you.

Should this part also explain what it is doing, just like we explained what happens when "make po-update" is run in an earlier section?

    The above sets up a clean filter for po/XX.po file so that the
    "msgcat --no-location" command is used to strip out the location
    information from the contents when the file is checked in.

or something, perhaps?