undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

l10n: Document the new l10n workflow

Browse Source 
Change the "flow" of how translators interact with the l10n repository
at [1] to adjust it for a new workflow of not having a po/git.pot file
in-tree at all, and to not commit line numbers to the po/*.po files
that we do track in tree.

The current workflow was added in a combination of dce37b66fb (l10n:
initial git.pot for 1.7.10 upcoming release, 2012-02-13) and
271ce198cd (Update l10n guide, 2012-02-29).

As noted in preceding commits I think that it came about due to
technical debt I'd left behind in how the "po/git.pot" file was
created, and a mis-impression that the file:line comments were needed
as anything more than a transitory translation aid.

As the updated po/README.md shows the new workflow is substantially
the same, the difference is that translators no longer need to
initially pull from the l10n coordinator for a new po/git.pot, they
can simply use git.git's canonical source repository.

The l10n coordinator is still expected to announce a release to
translate, which presumably would always be Junio's latest release
tag. I'm not certain if this part of the process is actually
important. I.e. the delta translation-wise between that tag and
"master" is usually pretty small, so perhaps translators can just work
on "master" instead.

1. https://github.com/git-l10n/git-po/

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Jiang Xin <zhiyou.jx@alibaba-inc.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Ævar Arnfjörð Bjarmason 2022-05-26 22:50:35 +08:00 committed by Junio C Hamano
parent b9832f7e3b
commit e2f4045fc4
1 changed files with 122 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

240
po/README.md
View File

@ -9,8 +9,14 @@ coordinates our localization effort in the l10 coordinator repository:
https://github.com/git-l10n/git-po/
The two character language translation codes are defined by ISO\_639-1, as
stated in the gettext(1) full manual, appendix A.1, Usual Language Codes.
We will use XX as an alias to refer to the language translation code in
the following paragraphs, for example we use "po/XX.po" to refer to the
translation file for a specific language. But this doesn't mean that
the language code has only two letters. The language code can be in one
of two forms: "ll" or "ll\_CC". Here "ll" is the ISO 639 two-letter
language code and "CC" is the ISO 3166 two-letter code for country names
and subdivisions. For example: "de" for German language code, "zh\_CN"
for Simplified Chinese language code.
## Contributing to an existing translation
@ -39,72 +45,74 @@ language, so that the l10n coordinator only needs to interact with one
person per language.
## Core translation
The core translation is the smallest set of work that must be completed
for a new language translation. Because there are more than 5000 messages
in the template message file "po/git.pot" that need to be translated,
this is not a piece of cake for the contributor for a new language.
The core template message file which contains a small set of messages
will be generated in "po-core/core.pot" automatically by running a helper
program named "git-po-helper" (described later).
```shell
git-po-helper init --core XX.po
```
After translating the generated "po-core/XX.po", you can merge it to
"po/XX.po" using the following commands:
```shell
msgcat po-core/XX.po po/XX.po -s -o /tmp/XX.po
mv /tmp/XX.po po/XX.po
git-po-helper update XX.po
```
Edit "po/XX.po" by hand to fix "fuzzy" messages, which may have misplaced
translated messages and duplicate messages.
## Translation Process Flow
The overall data-flow looks like this:
+-------------------+ +------------------+
| Git source code | ---(1)---> | L10n coordinator |
| repository | <---(4)--- | repository |
+-------------------+ +------------------+
| ^
(2) (3)
V |
+------------------+
| Language Team XX |
+------------------+
+-------------------+ +------------------+
| Git source code | ----(2)---> | L10n coordinator |
| repository | <---(5)---- | repository |
+-------------------+ +------------------+
| | ^
(1) (3) (4)
V v |
+----------------------------------+
| Language Team XX |
+----------------------------------+
- Translatable strings are marked in the source file.
- L10n coordinator pulls from the source (1)
- L10n coordinator updates the message template "po/git.pot"
- Language team pulls from L10n coordinator (2)
- Language team updates the message file "po/XX.po"
- L10n coordinator pulls from Language team (3)
- L10n coordinator asks the result to be pulled (4).
- Language teams can start translation iterations at any time, even
before the l10n window opens:
+ Pull from the master branch of the source (1)
+ Update the message file by running "make po-update PO\_FILE=po/XX.po"
+ Translate the message file "po/XX.po"
- The L10n coordinator pulls from source and announces the l10n window
open (2)
- Language team pulls from the l10n coordinator, starts another
translation iteration against the l10n coordinator's tree (3)
+ Run "git pull --rebase" from the l10n coordinator
+ Update the message file by running "make po-update PO\_FILE=po/XX.po"
+ Translate the message file "po/XX.po"
+ Squash trivial l10n git commits using "git rebase -i"
- Language team sends pull request to the l10n coordinator (4)
- L10n coordinator checks and merges
- L10n coordinator asks the result to be pulled (5).
## Maintaining the "po/git.pot" file
## Dynamically generated POT files
(This is done by the l10n coordinator).
POT files are templates for l10n contributors to create or update their
translation files. We used to have the "po/git.pot" file which was
generated by the l10n coordinator, but this file had been removed from
the tree.
The "po/git.pot" file contains a message catalog extracted from Git's
sources. The l10n coordinator maintains it by adding new translations with
msginit(1), or update existing ones with msgmerge(1). In order to update
the Git sources to extract the messages from, the l10n coordinator is
expected to pull from the main git repository at strategic point in
history (e.g. when a major release and release candidates are tagged),
and then run "make pot" at the top-level directory.
The two POT files "po/git.pot" and "po/git-core.pot" can be created
dynamically when necessary.
Language contributors use this file to prepare translations for their
language, but they are not expected to modify it.
L10n contributors use "po/git.pot" to prepare translations for their
languages, but they are not expected to modify it. The "po/git.pot" file
can be generated manually with the following command:
```shell
make po/git.pot
```
The "po/git-core.pot" file is the template for core translations. A core
translation is the minimum set of work necessary to complete a
translation of a new language. Since there are more than 5000 messages
in the full set of template message file "po/git.pot" that need to be
translated, this is not a piece of cake for new language contributors.
The "core" template file "po/git-core.pot" can be generated manually
by running:
```shell
make po/git-core.pot
```
## Initializing a "XX.po" file
@ -115,32 +123,14 @@ If your language XX does not have translated message file "po/XX.po" yet,
you add a translation for the first time by running:
```shell
msginit --locale=XX
make po-init PO_FILE=po/XX.po
```
in the "po/" directory, where XX is the locale, e.g. "de", "is", "pt\_BR",
"zh\_CN", etc.
where XX is the locale, e.g. "de", "is", "pt\_BR", "zh\_CN", etc.
Then edit the automatically generated copyright info in your new "XX.po"
to be correct, e.g. for Icelandic:
```diff
@@ -1,6 +1,6 @@
-# Icelandic translations for PACKAGE package.
-# Copyright (C) 2010 THE PACKAGE'S COPYRIGHT HOLDER
-# This file is distributed under the same license as the PACKAGE package.
+# Icelandic translations for Git.
+# Copyright (C) 2010 Ævar Arnfjörð Bjarmason <avarab@gmail.com>
+# This file is distributed under the same license as the Git package.
# Ævar Arnfjörð Bjarmason <avarab@gmail.com>, 2010.
```
And change references to PACKAGE VERSION in the PO Header Entry to
just "Git":
```shell
perl -pi -e 's/(?<="Project-Id-Version: )PACKAGE VERSION/Git/' XX.po
```
The newly generated message file "po/XX.po" is based on the core pot
file "po/git-core.pot", so it contains only a minimal set of messages
and it's a good start for a new language contribution.
Once you are done testing the translation (see below), commit the result
and ask the l10n coordinator to pull from you.
@ -153,19 +143,53 @@ and ask the l10n coordinator to pull from you.
If you are replacing translation strings in an existing "XX.po" file to
improve the translation, just edit the file.
If there's an existing "XX.po" file for your language, but the repository
of the l10n coordinator has newer "po/git.pot" file, you would need to first
pull from the l10n coordinator (see the beginning of this document for its
URL), and then update the existing translation by running:
If you want to find new translatable strings in source files of upstream
repository and propagate them to your "po/XX.po", run command:
```shell
msgmerge --add-location --backup=off -U XX.po git.pot
make po-update PO_FILE=po/XX.po
```
in the "po/" directory, where "XX.po" is the file you want to update.
It will:
Once you are done testing the translation (see below), commit the result
and ask the l10n coordinator to pull from you.
- Call "make po/git.pot" to generate new "po/git.pot" file
- 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 locate
translation context easily.
Once you are done testing the translation (see below), it's better
to commit a location-less "po/XX.po" file to save repository space
and make a user-friendly patch for review.
To save a location-less "po/XX.po" automatically in repository, you
can:
First define a new attribute for "po/XX.po" by appending the following
line in ".git/info/attributes":
```
/po/XX.po filter=gettext-no-location
```
Then define the driver for the "gettext-no-location" clean filter to
strip out both filenames and locations from the contents as follows:
```shell
git config --global filter.gettext-no-location.clean \
"msgcat --no-location -"
```
For users who have gettext version 0.20 or higher, it is also possible
to define a clean filter to preserve filenames but not locations:
```shell
git config --global filter.gettext-no-location.clean \
"msgcat --add-location=file -"
```
You're now ready to ask the l10n coordinator to pull from you.
## Fuzzy translation
@ -196,6 +220,14 @@ common errors, e.g. missing printf format strings, or translated
messages that deviate from the originals in whether they begin/end
with a newline or not.
L10n coordinator will check your contributions using a helper program
(see "PO helper" section below):
```shell
git-po-helper check-po po/XX.po
git-po-helper check-commits <rev-list-opts>
```
## Marking strings for translation
@ -370,29 +402,6 @@ l10n workflow.
To build and install the helper program from source, see
[git-po-helper/README][].
Usage for git-po-helper:
- To start a new language translation:
```shell
git-po-helper init XX.po
```
- To update your "XX.po" file:
```shell
git-po-helper update XX.po
```
- To check commit log and syntax of "XX.po":
```shell
git-po-helper check-po XX.po
git-po-helper check-commits
```
Run "git-po-helper" without arguments to show usage.
## Conventions
@ -436,13 +445,8 @@ additional conventions:
- Initialize proper filename of the "XX.po" file conforming to
iso-639 and iso-3166.
- Must complete a minimal translation based on the "po-core/core.pot"
template. Using the following command to initialize the minimal
"po-core/XX.po" file:
```shell
git-po-helper init --core <your-language>
```
- Must complete a minimal translation based on the "Core
translation". See that section above.
- Add a new entry in the "po/TEAMS" file with proper format, and check
the syntax of "po/TEAMS" by running the following command: