From: Jiang Xin <worldhello.net@gmail•com>
To: Git List <git@vger•kernel.org>
Cc: Jiang Xin <worldhello.net@gmail•com>
Subject: [RFC PATCH 2/2] l10n: README: document AI assistant guidelines
Date: Thu, 5 Feb 2026 21:00:28 +0800 [thread overview]
Message-ID: <71bfd9231e339cf43af86cfbffbbdde753d3fb82.1770296405.git.worldhello.net@gmail.com> (raw)
In-Reply-To: <CANYiYbFhshDwfttKWYGDfO+K1qAz3ptVHuuHrWXhD2oYBF7baQ@mail.gmail.com>
Add guidelines for using AI tools as optional assistants in Git
localization work, while emphasizing human translators remain in
control.
Also update `git-po-helper` command examples to include the
`--pot-file=build` option.
Example usage in prompts to AI assistants:
- "Update translations in `po/XX.po` following the guidelines
in @po/README.md"
- "Review all translations in `po/XX.po` following the guidelines
in @po/README.md"
Signed-off-by: Jiang Xin <worldhello.net@gmail•com>
---
po/README.md | 294 ++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 291 insertions(+), 3 deletions(-)
diff --git a/po/README.md b/po/README.md
index ad7f72ba83..6ba082376a 100644
--- a/po/README.md
+++ b/po/README.md
@@ -227,8 +227,8 @@ 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>
+git-po-helper check-po --pot-file=build po/XX.po
+git-po-helper check-commits --pot-file=build <rev-list-opts>
```
@@ -430,7 +430,7 @@ There are some conventions that l10n contributors must follow:
your commit:
```shell
- git-po-helper check-po <XX.po>
+ git-po-helper check-po --pot-file=build <XX.po>
```
- Squash trivial commits to make history clear.
@@ -459,5 +459,293 @@ additional conventions:
```
+## Artificial Intelligence (AI) as Translation Assistant
+
+This section provides guidance for human translators who choose to use AI tools
+as assistants in their localization work. The use of AI is entirely optional.
+Many successful translation teams work effectively without it.
+
+
+### Human translators remain in control
+
+Translation of Git is a human-driven community effort. Language team leaders and
+contributors are responsible for:
+
+- Understanding the technical context of Git commands and messages
+- Making linguistic and cultural adaptation decisions for their target language
+- Maintaining translation quality and consistency within their language team
+- Ensuring translations follow Git l10n conventions and community standards
+- Building and maintaining language-specific glossaries
+- Reviewing and approving all changes before submission
+
+AI tools, if used, serve only to accelerate routine tasks. They do not make
+decisions, do not replace human judgment, and do not understand cultural
+nuances or community needs.
+
+
+### When AI assistance may be helpful
+
+AI tools can help speed up certain mechanical aspects of translation work:
+
+- Generating first-draft translations for new or updated messages
+- Identifying untranslated or fuzzy entries across large PO files
+- Checking consistency with existing translations and glossary terms
+- Detecting technical errors (missing placeholders, formatting issues)
+- Reviewing translations against quality criteria
+
+However, AI-generated output should always be treated as rough drafts requiring
+human review, editing, and approval by someone who understands both the
+technical context and the target language.
+
+
+### Preparing your translation environment for effective AI use
+
+If you choose to use AI assistance, investing time in preparation will
+significantly improve the quality of AI-generated suggestions:
+
+1. **Maintain a glossary**: Add a "Git glossary for XX translators" section in
+ the header comments of your `po/XX.po` file (before the first `msgid`). List
+ key Git terms with their approved translations. AI tools can read and follow
+ this glossary.
+
+2. **Keep translations up-to-date**: Regularly sync your `po/XX.po` with
+ upstream. AI learns from existing translations. The more complete and
+ consistent your PO file, the better AI suggestions will be.
+
+3. **Document style guidelines**: If your language team has specific formatting
+ or style preferences, document them in your `po/XX.po` header. AI can
+ incorporate these guidelines into its output.
+
+4. **Choose appropriate AI coding tools**: Evaluate and use models and tools
+ that work best for your target language. Different AI models have varying
+ levels of proficiency across languages. Test multiple tools to find which
+ produces the most natural and accurate translations for your language.
+
+
+### Technical guidelines for AI tools
+
+The following sections provide technical specifications for AI tools that
+assist with Git translation. These guidelines ensure AI-generated suggestions
+are technically correct and follow Git l10n conventions. Human translators
+should be familiar with these requirements to effectively review AI output.
+
+
+#### Scope and context
+
+- Primary files: `po/XX.po` for translations, `po/git.pot` for the source
+ template (generated on demand; see "Dynamically generated POT files").
+- Source language: English. Target language: derived from the language code in
+ the `po/XX.po` filename based on ISO 639 and ISO 3166.
+- Glossary: Git l10n teams may add glossary sections (e.g. "Git glossary for
+ Chinese translators") in the header comments of `po/XX.po` immediately before
+ the first `msgid` entry. If a glossary exists, read it and keep terminology
+ consistent.
+
+
+#### Quality checklist
+
+- Accuracy: faithfully conveys the original meaning; no omissions or distortions.
+- Terminology: uses correct, consistent terms per glossary or domain standards.
+- Grammar and fluency: grammatically correct and reads naturally.
+- Placeholders: preserves variables (e.g. `%s`, `{name}`, `$1`) exactly. If
+ reordering is needed for the target language, use positional parameters as
+ described below.
+- Plurals and gender: handles plural forms, gender, and agreement correctly.
+- Context fit: suitable for UI space, tone, and usage (e.g. error vs. tooltip).
+- Cultural appropriateness: avoids offensive or ambiguous content.
+- Consistency: matches prior translations of the same source string.
+- Technical integrity: do not translate code, paths, commands, brand names, or
+ proper nouns.
+- Readability: clear, concise, and user-friendly.
+
+
+#### Locating untranslated, fuzzy, and obsolete entries
+
+Use GNU gettext tools to parse PO structure reliably (safe for multi-line
+`msgid`/`msgstr`):
+
+- Untranslated entries:
+
+ ```shell
+ msgattrib --untranslated --no-obsolete po/XX.po
+ ```
+
+- Fuzzy entries:
+
+ ```shell
+ msgattrib --only-fuzzy --no-obsolete po/XX.po
+ ```
+
+- Obsolete entries (marked with `#~`):
+
+ ```shell
+ msgattrib --obsolete --no-wrap po/XX.po
+ ```
+
+If you only want the message IDs, you can pipe to:
+
+```shell
+msgattrib --untranslated --no-obsolete po/XX.po | sed -n '/^msgid /,/^$/p'
+```
+
+```shell
+msgattrib --only-fuzzy --no-obsolete po/XX.po | sed -n '/^msgid /,/^$/p'
+```
+
+
+#### Translation workflow (`po/XX.po`)
+
+When asked to update translations, follow the steps in this section in order
+and reference this section in your plan before making edits.
+
+- Generate `po/git.pot` from source code (see "Dynamically generated POT files").
+- Update `po/XX.po` with the new template.
+- Translate new entries identified by `msgattrib --untranslated` (see above).
+- Fix fuzzy entries identified by `msgattrib --only-fuzzy` (see above) by
+ re-translating and removing the `fuzzy` tag after updating `msgstr`.
+- For entries with `msgid_plural`, consult [Plural forms](#plural-forms) to
+ supply all required `msgstr[n]` forms based on the `Plural-Forms` header.
+- Apply the quality checklist to every translation.
+
+
+#### Review workflow
+
+Review workflow has two modes: direct review against local `po/XX.po`, and
+review based on a patch.
+
+##### Full file review
+
+- When explicitly asked to review all translated content, review `po/XX.po`
+ in chunks (see [Handling large inputs](#handling-large-inputs) for splitting).
+- Apply the quality checklist to each message you review.
+- Unless otherwise specified, update `po/XX.po` directly; if a summary is
+ requested, provide a consolidated report of the issues.
+
+
+##### Patch review
+
+- Review requests may come as patches of `po/XX.po`:
+ - Workspace changes: `git diff HEAD -- po/XX.po`
+ - Changes since a commit-ish: `git diff <commit-ish> -- po/XX.po`
+ - Changes in a specific commit: `git show <commit-ish> -- po/XX.po`
+- For large patches, follow the split guidance in
+ [Handling large inputs](#handling-large-inputs) when splitting.
+- When diff context is incomplete (truncated `msgid` or `msgstr`), use file
+ viewing tools to pull nearby context for accurate review.
+- Apply the same quality checklist as in full file reviews.
+- If the patch is based on workspace changes, update `po/XX.po` directly
+ unless a summary is requested.
+- If the patch is from a specific commit, report issues or apply fixes when
+ comparing against the current `po/XX.po` in the workspace.
+
+
+#### Handling large inputs
+
+When a `po/XX.po` file or a patch is too large for LLM context, split it into
+chunks while keeping `msgid` and `msgstr` pairs intact. This includes plural
+forms: `msgid`, `msgid_plural`, `msgstr[0]`, `msgstr[1]`, and any additional
+plural indices required by the language.
+
+For `po/XX.po`, split on the line immediately before each `msgid` entry. This
+guarantees no chunk begins with an unpaired `msgid`. Use
+`grep -n '^msgid' po/XX.po` to locate split points, and group the file into
+chunks of no more than 200 `msgid` entries (about 50K bytes each).
+
+For patch files, check the patch size first:
+
+- If the patch is <= 100KB, do not split.
+- If the patch is > 100KB, split it using the same rule as for `po/XX.po`:
+ split on the line immediately before each `msgid` entry so message pairs
+ stay together.
+
+
+#### Plural forms
+
+This section defines how translators should handle `msgid_plural` entries,
+including how many `msgstr[n]` forms are required and how to index them. It
+provides the canonical example and points to the `Plural-Forms` header for the
+language-specific rule set.
+
+For entries with `msgid_plural`, provide plural forms:
+
+```po
+msgid "..."
+msgid_plural "..."
+msgstr[0] "..."
+msgstr[1] "..."
+```
+
+Use `msgstr[0]`/`msgstr[1]` as required. If the language has more plural forms,
+follow the `Plural-Forms` header in `po/XX.po` to determine the required number
+of `msgstr[n]` entries.
+
+
+#### Placeholder reordering
+
+When a translation reorders placeholders, mark them with positional parameter
+syntax (`%n$`) so each argument maps to the correct source value. Keep the
+width/precision modifiers intact and place the position specifier before them.
+
+Example:
+
+```po
+msgid "missing environment variable '%s' for configuration '%.*s'"
+msgstr "配置 '%3$.*2$s' 缺少环境变量 '%1$s'"
+```
+
+Here the translation swaps the two placeholders. `%1$s` still refers to the
+first argument (`%s`), while `%3$.*2$s` refers to the third string argument
+with the precision taken from the second argument (`%.*s`).
+
+
+### Integrating AI tools into your workflow
+
+If you decide to use AI assistance, here's how to integrate it responsibly:
+
+
+#### For AI tool developers and users
+
+When building or configuring AI-assisted translation tools:
+
+- Use the quality checklist (above) to score or filter draft suggestions
+- Apply the `msgattrib` + `sed` commands to extract relevant entries for processing
+- Ensure AI tools read and respect glossary terms from the `po/XX.po` header
+- Configure tools to follow the technical workflows documented above
+
+
+#### Human oversight is mandatory
+
+**Never submit AI-generated translations without human review.** The human
+translator must:
+
+- Verify technical accuracy (correct placeholders, plural forms, formatting)
+- Ensure linguistic quality (natural phrasing, appropriate terminology)
+- Check cultural appropriateness for the target audience
+- Confirm consistency with the language team's established style
+- Take full responsibility for the final translation
+
+Example usage in prompts to AI assistants:
+
+- "Update translations in `po/XX.po` following the guidelines in @po/README.md"
+- "Review all translations in `po/XX.po` following the guidelines in @po/README.md"
+
+
+### Summary: AI as a tool, humans as translators
+
+AI can accelerate translation work, but it is not a substitute for human
+translators. The Git localization community values:
+
+- **Human expertise**: Deep understanding of Git's technical context and the
+ cultural nuances of each target language
+- **Community standards**: Consistency across releases and alignment with
+ language team conventions
+- **Accountability**: Human translators who stand behind their work and respond
+ to feedback from users
+
+If you choose to use AI tools, they should enhance these human contributions,
+not replace them. The best results come from combining AI efficiency with human
+judgment, cultural insight, and community engagement.
+
+
[git-po-helper/README]: https://github.com/git-l10n/git-po-helper#readme
[Documentation/SubmittingPatches]: Documentation/SubmittingPatches
--
2.51.0.rc2
next prev parent reply other threads:[~2026-02-05 13:00 UTC|newest]
Thread overview: 45+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-02-04 9:31 [RFC] Introducing AI Agents to Git Localization Jiang Xin
2026-02-04 11:58 ` Peter Krefting
2026-02-04 13:00 ` Michal Suchánek
2026-02-04 14:38 ` 依云
2026-02-05 2:06 ` Jiang Xin
2026-02-05 8:30 ` Michal Suchánek
2026-02-05 11:16 ` Jiang Xin
2026-02-05 13:18 ` Michal Suchánek
2026-02-05 1:04 ` Jiang Xin
2026-02-05 1:53 ` brian m. carlson
[not found] ` <0207CD38-C811-499D-AFA6-131B0CA825CD@gmail.com>
2026-02-05 12:54 ` Jiang Xin
2026-02-05 13:00 ` [RFC PATCH 1/2] l10n: add .gitattributes to simplify location filtering Jiang Xin
2026-02-05 20:07 ` Junio C Hamano
2026-02-05 13:00 ` Jiang Xin [this message]
2026-02-05 20:35 ` [RFC PATCH 2/2] l10n: README: document AI assistant guidelines Junio C Hamano
2026-02-06 2:38 ` Jiang Xin
2026-03-03 15:33 ` [PATCH v2 0/5] docs(l10n): AI agent instructions and workflow improvements Jiang Xin
2026-03-03 15:33 ` [PATCH v2 1/5] l10n: add .gitattributes to simplify location filtering Jiang Xin
2026-03-03 15:33 ` [PATCH v2 2/5] docs(l10n): add AGENTS.md with optimized update-pot instructions Jiang Xin
2026-03-12 2:11 ` Jiang Xin
2026-03-03 15:33 ` [PATCH v2 3/5] docs(l10n): add AI agent instructions for updating po/XX.po files Jiang Xin
2026-03-03 15:33 ` [PATCH v2 4/5] docs(l10n): add AI agent instructions for translating PO files Jiang Xin
2026-03-12 2:26 ` Jiang Xin
2026-03-03 15:33 ` [PATCH v2 5/5] docs(l10n): add AI agent instructions to review translations Jiang Xin
2026-03-12 2:34 ` Jiang Xin
2026-03-14 14:38 ` [PATCH v3 0/5] docs(l10n): AI agent instructions and workflow improvements Jiang Xin
2026-03-14 14:38 ` [PATCH v3 1/5] l10n: add .gitattributes to simplify location filtering Jiang Xin
2026-03-15 11:13 ` Johannes Sixt
2026-03-15 16:11 ` Junio C Hamano
2026-03-16 5:44 ` Jiang Xin
2026-03-16 3:21 ` Jiang Xin
2026-03-16 12:43 ` Johannes Sixt
2026-03-14 14:38 ` [PATCH v3 2/5] docs(l10n): add AGENTS.md with optimized update-pot instructions Jiang Xin
2026-03-14 14:38 ` [PATCH v3 3/5] docs(l10n): add AI agent instructions for updating po/XX.po files Jiang Xin
2026-03-14 14:38 ` [PATCH v3 4/5] docs(l10n): add AI agent instructions for translating PO files Jiang Xin
2026-03-14 14:38 ` [PATCH v3 5/5] docs(l10n): add AI agent instructions to review translations Jiang Xin
2026-03-16 23:54 ` [PATCH v4 0/5] docs(l10n): AI agent instructions and workflow improvements Jiang Xin
2026-03-16 23:54 ` [PATCH v4 1/5] l10n: add .gitattributes to simplify location filtering Jiang Xin
2026-03-16 23:54 ` [PATCH v4 2/5] docs(l10n): add AGENTS.md with optimized update-pot instructions Jiang Xin
2026-03-16 23:54 ` [PATCH v4 3/5] docs(l10n): add AI agent instructions for updating po/XX.po files Jiang Xin
2026-03-16 23:54 ` [PATCH v4 4/5] docs(l10n): add AI agent instructions for translating PO files Jiang Xin
2026-03-16 23:54 ` [PATCH v4 5/5] docs(l10n): add AI agent instructions to review translations Jiang Xin
2026-03-31 0:52 ` [PATCH v4 0/5] docs(l10n): AI agent instructions and workflow improvements Jiang Xin
2026-03-31 3:38 ` Junio C Hamano
2026-03-31 4:37 ` Jiang Xin
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=71bfd9231e339cf43af86cfbffbbdde753d3fb82.1770296405.git.worldhello.net@gmail.com \
--to=worldhello.net@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox