Re: [RFC PATCH 2/2] l10n: README: document AI assistant guidelines

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 5, 2026, 20:35 UTC
Message-ID: <xmqqfr7fkjx4.fsf@gitster.g>
In-Reply-To: <71bfd9231e339cf43af86cfbffbbdde753d3fb82.1770296405.git.worldhello.net@gmail.com>

Jiang Xin <worldhello.net@gmail.com> writes:

Show 43 quoted lines

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

Is everything above specific to using AI assistants to help your translation process, or do people who do not (yet) use them also benefit from these updated examples? If the latter, it probably should belong to a separate patch.

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

They may very well do any of the above. It is your responsibility as humans to monitor their decisions, judgement, and understanding, and countermand them as needed.

Show 9 quoted lines

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

A few random sampling of po/XX.po files seems to tell me that this is already the case for some languages but no all of them. Perhaps refer translators for other languages an existing example to help them start their glossary in their po/XX.po file?

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

I am not sure what this means. When you are working on updating translations for your language, you'd want to be working from or near the tip anyway, regardless of what tools you would use, no?

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

If we have an example in po/XY.po that translators to other languages can learn from?

Show 12 quoted lines

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

Are the subsections of this section meant to be fed as part of prompt to the tools? Otherwise they look mostly repetitions of what human translators already have learned elsewhere in the document.

Show 10 quoted lines

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

This overlaps "Preparing #1"; do you want to cover "Preparing #4" as well?

Show 15 quoted lines

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

The fact that these are important does not change if you use AI tools or not, no? As I am not sure the purpose of these repeated instructions in the "Tech guidelines for AI tools" section, I've trimmed most of the contents in it here.

Show 11 quoted lines

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

Referring to the section (e.g., "commands listed in the 'Locating untranslated, fuzzy, and obsolete entries' section") would be clearer. You have necessary commands ready to be cut-and-pasted there.