git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v4 9/9] l10n: Document the new l10n workflow

From
Jiang Xin <worldhello.net@gmail.com>
Date
May 23, 2022, 15:21 UTC
Message-ID
<20220523152128.26380-10-worldhello.net@gmail.com>
In-Reply-To
<20220523012531.4505-1-worldhello.net@gmail.com>
From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>

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 dce37b66fb0 (l10n: initial git.pot for 1.7.10 upcoming release, 2012-02-13) and 271ce198cd0 (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>
---
 po/README.md | 230 ++++++++++++++++++++++++++-------------------------
 1 file changed, 117 insertions(+), 113 deletions(-)
diff --git a/po/README.md b/po/README.md
index 19fabb4acf..74856ca5bf 100644
--- a/po/README.md
+++ b/po/README.md
@@ -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
+## Translation Process Flow
 
-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 overall data-flow looks like this:
 
-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).
+    +-------------------+             +------------------+
+    | Git source code   | ----(2)---> | L10n coordinator |
+    | repository        | <---(5)---- | repository       |
+    +-------------------+             +------------------+
+                    |                     |    ^
+                   (1)                   (3)  (4)
+                    V                     v    |
+               +----------------------------------+
+               |        Language Team XX          |
+               +----------------------------------+
 
-```shell
-git-po-helper init --core XX.po
-```
+- Translatable strings are marked in the source file.
+- Language teams can start translation iterations at any time, even
+  before the l10n window opens:
 
-After translating the generated "po-core/XX.po", you can merge it to
-"po/XX.po" using the following commands:
+  + 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"
 
-```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
-```
+- 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)
 
-Edit "po/XX.po" by hand to fix "fuzzy" messages, which may have misplaced
-translated messages and duplicate messages.
+  + 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).
 
-## Translation Process Flow
 
-The overall data-flow looks like this:
+## Dynamically generated POT files
 
-    +-------------------+            +------------------+
-    | Git source code   | ---(1)---> | L10n coordinator |
-    | repository        | <---(4)--- | repository       |
-    +-------------------+            +------------------+
-                                          |      ^
-                                         (2)    (3)
-                                          V      |
-                                     +------------------+
-                                     | Language Team XX |
-                                     +------------------+
+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.
 
-- 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).
+The two POT files "po/git.pot" and "po/git-core.pot" can be created
+dynamically when necessary.
 
+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:
 
-## Maintaining the "po/git.pot" file
+```shell
+make po/git.pot
+```
 
-(This is done by the l10n coordinator).
+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 "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 "core" template file "po/git-core.pot" can be generated manually
+by running:
 
-Language contributors use this file to prepare translations for their
-language, but they are not expected to modify it.
+```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.
-
-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":
+where XX is the locale, e.g. "de", "is", "pt\_BR", "zh\_CN", etc.
 
-```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:

-- 
2.36.0.1.g15c4090757
Previous: Jiang XinNext: Jiang Xin
Message 70 of 110 in “Incremental po/git.pot update and new l10n workflow”
  1. 0/9 Incremental po/git.pot update and new l10n workflowJiang Xin, May 3, 2022
  2. 1/9 Makefile: sort "po/git.pot" by file locationJiang Xin, May 3, 2022
  3. 2/9 Makefile: generate "po/git.pot" from stable LOCALIZED_CJiang Xin, May 3, 2022
  4. 5/9 po/git.pot: don't check in result of "make pot"Jiang Xin, May 3, 2022
  5. 3/9 Makefile: have "make pot" not "reset --hard"Jiang Xin, May 3, 2022
  6. 7/9 Makefile: add "po-update" rule to update po/XX.poJiang Xin, May 3, 2022
  7. 9/9 l10n: Document the new l10n workflowJiang Xin, May 3, 2022
  8. 8/9 Makefile: add "po-init" rule to initialize po/XX.poJiang Xin, May 3, 2022
  9. 4/9 i18n CI: stop allowing non-ASCII source messages in po/git.potJiang Xin, May 3, 2022
  10. 6/9 po/git.pot: remove this now generated file, see preceding commitJiang Xin, May 3, 2022
  11. Peter KreftingMay 3, 2022
  12. Jiang XinMay 4, 2022
  13. Junio C HamanoMay 4, 2022
  14. Daniel SantosMay 4, 2022
  15. Jiang XinMay 5, 2022
  16. Daniel SantosMay 5, 2022
  17. Junio C HamanoMay 5, 2022
  18. Jiang XinMay 6, 2022
  19. Jiang XinMay 5, 2022
  20. Junio C HamanoMay 4, 2022
  21. 1/9 Makefile: sort "po/git.pot" by file locationJiang Xin, May 19, 2022
  22. Ævar Arnfjörð BjarmasonMay 19, 2022
  23. Jiang XinMay 19, 2022
  24. 0/9 Incremental po/git.pot update and new l10n workflowJiang Xin, May 19, 2022
  25. Ævar Arnfjörð BjarmasonMay 19, 2022
  26. Jiang XinMay 19, 2022
  27. Ævar Arnfjörð BjarmasonMay 19, 2022
  28. 0/9 Incremental po/git.pot update and new l10n workflowJiang Xin, May 23, 2022
  29. Ævar Arnfjörð BjarmasonMay 23, 2022
  30. Ævar Arnfjörð BjarmasonMay 23, 2022
  31. Jiang XinMay 23, 2022
  32. Ævar Arnfjörð BjarmasonMay 23, 2022
  33. Jiang XinMay 23, 2022
  34. Jiang XinMay 23, 2022
  35. 0/9 Incremental po/git.pot update and new l10n workflowJiang Xin, May 23, 2022
  36. Junio C HamanoMay 23, 2022
  37. 01/10 Makefile: sort source files before feeding to xgettextJiang Xin, May 26, 2022
  38. 00/10 Incremental po/git.pot update and new l10n workflowJiang Xin, May 26, 2022
  39. 02/10 Makefile: generate "po/git.pot" from stable LOCALIZED_CJiang Xin, May 26, 2022
  40. 10/10 l10n: Document the new l10n workflowJiang Xin, May 26, 2022
  41. 06/10 po/git.pot: this is now a generated fileJiang Xin, May 26, 2022
  42. Junio C HamanoMay 26, 2022
  43. 04/10 i18n CI: stop allowing non-ASCII source messages in po/git.potJiang Xin, May 26, 2022
  44. 05/10 Makefile: remove duplicate and unwanted files in FOUND_SOURCE_FILESJiang Xin, May 26, 2022
  45. 08/10 Makefile: add "po-update" rule to update po/XX.poJiang Xin, May 26, 2022
  46. 07/10 po/git.pot: don't check in result of "make pot"Jiang Xin, May 26, 2022
  47. 09/10 Makefile: add "po-init" rule to initialize po/XX.poJiang Xin, May 26, 2022
  48. 03/10 Makefile: have "make pot" not "reset --hard"Jiang Xin, May 26, 2022
  49. 2/9 Makefile: generate "po/git.pot" from stable LOCALIZED_CJiang Xin, May 23, 2022
  50. 7/9 Makefile: add "po-update" rule to update po/XX.poJiang Xin, May 23, 2022
  51. 1/9 Makefile: sort "po/git.pot" by file locationJiang Xin, May 23, 2022
  52. 4/9 i18n CI: stop allowing non-ASCII source messages in po/git.potJiang Xin, May 23, 2022
  53. 3/9 Makefile: have "make pot" not "reset --hard"Jiang Xin, May 23, 2022
  54. Junio C HamanoMay 25, 2022
  55. Junio C HamanoMay 25, 2022
  56. Jiang XinMay 26, 2022
  57. Makefile: dedup git-ls-files output to prevent duplicate targetsJiang Xin, May 26, 2022
  58. Junio C HamanoMay 26, 2022
  59. Jiang XinMay 26, 2022
  60. Junio C HamanoMay 26, 2022
  61. Jiang XinMay 26, 2022
  62. Ævar Arnfjörð BjarmasonMay 26, 2022
  63. Jiang XinMay 26, 2022
  64. Junio C HamanoMay 26, 2022
  65. Ævar Arnfjörð BjarmasonMay 26, 2022
  66. Junio C HamanoMay 26, 2022
  67. Ævar Arnfjörð BjarmasonMay 26, 2022
  68. 6/9 po/git.pot: don't check in result of "make pot"Jiang Xin, May 23, 2022
  69. 5/9 po/git.pot: this is now a generated fileJiang Xin, May 23, 2022
  70. 9/9 l10n: Document the new l10n workflowJiang Xin, May 23, 2022
  71. 8/9 Makefile: add "po-init" rule to initialize po/XX.poJiang Xin, May 23, 2022
  72. 1/9 Makefile: sort "po/git.pot" by file locationJiang Xin, May 23, 2022
  73. Junio C HamanoMay 23, 2022
  74. Jiang XinMay 23, 2022
  75. 2/9 Makefile: generate "po/git.pot" from stable LOCALIZED_CJiang Xin, May 23, 2022
  76. Junio C HamanoMay 23, 2022
  77. 9/9 l10n: Document the new l10n workflowJiang Xin, May 23, 2022
  78. 7/9 Makefile: add "po-update" rule to update po/XX.poJiang Xin, May 23, 2022
  79. 8/9 Makefile: add "po-init" rule to initialize po/XX.poJiang Xin, May 23, 2022
  80. 3/9 Makefile: have "make pot" not "reset --hard"Jiang Xin, May 23, 2022
  81. Ævar Arnfjörð BjarmasonMay 23, 2022
  82. Jiang XinMay 23, 2022
  83. Jiang XinMay 24, 2022
  84. Junio C HamanoMay 23, 2022
  85. Jiang XinMay 23, 2022
  86. 4/9 i18n CI: stop allowing non-ASCII source messages in po/git.potJiang Xin, May 23, 2022
  87. 6/9 po/git.pot: don't check in result of "make pot"Jiang Xin, May 23, 2022
  88. Ævar Arnfjörð BjarmasonMay 23, 2022
  89. Jiang XinMay 23, 2022
  90. Jiang XinMay 23, 2022
  91. Ævar Arnfjörð BjarmasonMay 23, 2022
  92. 5/9 po/git.pot: this is now a generated fileJiang Xin, May 23, 2022
  93. 2/9 Makefile: generate "po/git.pot" from stable LOCALIZED_CJiang Xin, May 19, 2022
  94. Ævar Arnfjörð BjarmasonMay 19, 2022
  95. Jiang XinMay 19, 2022
  96. 3/9 Makefile: have "make pot" not "reset --hard"Jiang Xin, May 19, 2022
  97. Ævar Arnfjörð BjarmasonMay 19, 2022
  98. Jiang XinMay 19, 2022
  99. Ævar Arnfjörð BjarmasonMay 19, 2022
  100. 5/9 po/git.pot: this is now a generated fileJiang Xin, May 19, 2022
  101. 7/9 Makefile: add "po-update" rule to update po/XX.poJiang Xin, May 19, 2022
  102. Ævar Arnfjörð BjarmasonMay 19, 2022
  103. 6/9 po/git.pot: don't check in result of "make pot"Jiang Xin, May 19, 2022
  104. 8/9 Makefile: add "po-init" rule to initialize po/XX.poJiang Xin, May 19, 2022
  105. Ævar Arnfjörð BjarmasonMay 19, 2022
  106. 9/9 l10n: Document the new l10n workflowJiang Xin, May 19, 2022
  107. Junio C HamanoMay 19, 2022
  108. Jiang XinMay 21, 2022
  109. 4/9 i18n CI: stop allowing non-ASCII source messages in po/git.potJiang Xin, May 19, 2022
  110. Ævar Arnfjörð BjarmasonMay 19, 2022

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.