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

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