[PATCH 0/3] po/README: document miscellaneous topics mentioned by l10n coordinator

Document various topics mentioned by l10n coordinator (Jiang Xin) when
pulling l10n contributions.

Bagas Sanjaya (3):
  po/README: document PO helper
  po/README: document "core translation"
  po/README: document l10n conventions

 po/README | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

-- 
2.25.1

Document things that l10n contributors must folow.

Signed-off-by: Bagas Sanjaya <redacted>
---
 po/README | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/po/README b/po/README
index eda7edf4e6..e1a0494b17 100644
--- a/po/README
+++ b/po/README

@@ -344,3 +344,24 @@ Below are the usage examples:
         po-helper.sh check XX.po
 
 Run po-helper.sh without arguments for usage help.
+
+
+Conventions
+-----------
+
+There are some conventions that l10n contributors must follow:
+
+   1. The subject of each commit should be prefixed with `l10n: `.
+   2. The length of commit log title (subject) should be less than 50
+      characters, and the length of other lines (commit log body)
+      should be no more than 72 characters.
+   3. Add "Signed-off-by" trailer to your commit log, like other
+      commits in Git. You can automatically add the trailer by
+      committing with `git commit -s`.
+   4. Check syntax with `msgfmt` or `po-helper.sh check` before
+      committing.
+   5. Squash trivial commits to make history clear.
+   6. Do NOT edit files outside po/ directory.
+   7. Other subsystems ("git-gui", "gitk", and Git itself) have their
+      own workflow. See Documentation/SubmittingPatches if you want
+      to make contributions to these subsystems.

-- 
2.25.1

Document about PO helper script (po-helper.sh). It covers about
installing the script and short usage examples.

Signed-off-by: Bagas Sanjaya <redacted>
---
 po/README | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/po/README b/po/README
index efd5baaf1d..9beffc2954 100644
--- a/po/README
+++ b/po/README

@@ -286,3 +286,25 @@ Testing marked strings
 
 Git's tests are run under LANG=C LC_ALL=C. So the tests do not need be
 changed to account for translations as they're added.
+
+
+PO Helper
+---------
+
+To make maintaining XX.po file easier, the l10n coordinator created
+po-helper.sh script. It is wrapper to gettext suite, specifically
+written for the purpose of Git l10n workflow.
+
+To install the script, checkout "po-helper" branch, then copy
+utils/po-helper.sh to somewhere on $PATH, and mark it executable.
+
+Below are the usage examples:
+
+  - To start new language translation:
+        po-helper.sh init XX.po
+  - To update PO file:
+        po-helper.sh update XX.po
+  - To syntax check:
+        po-helper.sh check XX.po
+
+Run po-helper.sh without arguments for usage help.

-- 
2.25.1

We now expect new language translations to have core subset of 5000+
messages translated for these to be merged. If it hasn't been done yet,
do so by first generate core PO, then do translation work there, merge
it back to main PO (XX.po), and fix any "fuzzy" errors.

Signed-off-by: Bagas Sanjaya <redacted>
---
 po/README | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/po/README b/po/README
index 9beffc2954..eda7edf4e6 100644
--- a/po/README
+++ b/po/README

@@ -39,6 +39,42 @@ coordinate among yourselves and nominate the team leader for your
 language, so that the l10n coordinator only needs to interact with one
 person per language.
 
+Because there are now over 5000 messages that needs to be translated,
+we expect to complete translation for core subset of messages before
+a new language translation can be merged. See "Core translation"
+below.
+
+
+Core translation
+----------------
+The core translation file, core-XX.po, covers some of commonly used
+commands:
+
+  - wt-status.c
+  - builtin/clone.c
+  - builtin/checkout.c
+  - builtin/index-pack.c
+  - builtin/push.c
+  - builtin/reset.c
+
+To generate core-XX.po, install the helper script (see "PO Helper")
+and check the main PO file:
+
+    cd po/
+    po-helper.sh check id.po
+
+This will generate po/core-XX.po and corresponding po/core-XX.pot
+template. Now complete the translation in po/core-XX.po.
+
+When it is completed, merge core translation back to main PO file:
+
+    msgcat core-XX.po XX.po -s -o /tmp/XX.po
+    mv /tmp/XX.po XX.po
+    msgmerge --add-location --backup=off -U XX.po git.pot
+
+Fix any "fuzzy" errors that occurs, such as misplaced translated
+messages and duplicate messages.
+
 
 Translation Process Flow
 ------------------------

-- 
2.25.1

On 11/03/21 19.55, Bagas Sanjaya wrote:

Document things that l10n contributors must folow.

Signed-off-by: Bagas Sanjaya <redacted>
---
  po/README | 21 +++++++++++++++++++++
  1 file changed, 21 insertions(+)

Oh oh oh, typo there. folow -> follow.

-- 
An old man doll... just what I always wanted! - Clara

Bagas Sanjaya [off-list ref] 于2021年3月11日周四 下午8:56写道：

This patch 3/3 can be merged before we reimplement the utility `git-po-helper`.

--
Jiang Xin

Bagas Sanjaya [off-list ref] 于2021年3月11日周四 下午8:56写道：

s/id.po/XX.po/

+
+This will generate po/core-XX.po and corresponding po/core-XX.pot
+template. Now complete the translation in po/core-XX.po.
+
+When it is completed, merge core translation back to main PO file:
+
+    msgcat core-XX.po XX.po -s -o /tmp/XX.po
+    mv /tmp/XX.po XX.po
+    msgmerge --add-location --backup=off -U XX.po git.pot
+
+Fix any "fuzzy" errors that occurs, such as misplaced translated
+messages and duplicate messages.
+

 Translation Process Flow
 ------------------------
--
2.25.1

Bagas Sanjaya [off-list ref] 于2021年3月11日周四 下午8:56写道：

It's better to rename the script to other name without the suffix
".sh", so we can reimplement it in other programming language. Maybe
we can rename it to `git-po-helper`, and host this helper in a
separate project on GitHub.

+written for the purpose of Git l10n workflow.
+
+To install the script, checkout "po-helper" branch, then copy
+utils/po-helper.sh to somewhere on $PATH, and mark it executable.
+
+Below are the usage examples:
+
+  - To start new language translation:
+        po-helper.sh init XX.po
+  - To update PO file:
+        po-helper.sh update XX.po
+  - To syntax check:
+        po-helper.sh check XX.po
+
+Run po-helper.sh without arguments for usage help.
--
2.25.1

On 12/03/21 08.33, Jiang Xin wrote:

Bagas Sanjaya [off-list ref] 于2021年3月11日周四 下午8:56写道：

quoted

Document things that l10n contributors must folow.

Signed-off-by: Bagas Sanjaya <redacted>
---
  po/README | 21 +++++++++++++++++++++
  1 file changed, 21 insertions(+)

diff --git a/po/README b/po/README
index eda7edf4e6..e1a0494b17 100644
--- a/po/README
+++ b/po/README

@@ -344,3 +344,24 @@ Below are the usage examples:
          po-helper.sh check XX.po

  Run po-helper.sh without arguments for usage help.
+
+
+Conventions
+-----------
+
+There are some conventions that l10n contributors must follow:
+
+   1. The subject of each commit should be prefixed with `l10n: `.
+   2. The length of commit log title (subject) should be less than 50
+      characters, and the length of other lines (commit log body)
+      should be no more than 72 characters.
+   3. Add "Signed-off-by" trailer to your commit log, like other
+      commits in Git. You can automatically add the trailer by
+      committing with `git commit -s`.
+   4. Check syntax with `msgfmt` or `po-helper.sh check` before
+      committing.
+   5. Squash trivial commits to make history clear.
+   6. Do NOT edit files outside po/ directory.
+   7. Other subsystems ("git-gui", "gitk", and Git itself) have their
+      own workflow. See Documentation/SubmittingPatches if you want
+      to make contributions to these subsystems.

This patch 3/3 can be merged before we reimplement the utility `git-po-helper`.

--
Jiang Xin

Did you mean this patch can be sent separated from this series?

-- 
An old man doll... just what I always wanted! - Clara