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

[Junio C Hamano <gitster@pobox.com>]

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

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

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

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


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

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


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