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

[Junio C Hamano <gitster@pobox.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"

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

> @@ -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.

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

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