l10n: README: add AI agent guidelines

AI agents can significantly improve the efficiency and consistency of
localization tasks, including translation and quality assurance. Adds
clear guidelines to help AI agents perform these tasks more effectively
by referencing standardized practices.

Additionally, the `git-po-helper` command has been slightly adjusted
to better support AI agent workflows.

Examples of prompts for AI agents:
- Refer to @po/README.md to update translations in po/XX.po.
- Refer to @po/README.md to review all translations in po/XX.po.

Signed-off-by: Jiang Xin <worldhello.net@gmail.com>

Author: jiangxin

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,181 @@ additional conventions:
   ```
 
 
+## AI Agent Guidelines
+
+These guidelines help AI agents translate and review Git core messages
+consistently and accurately.
+
+### Scope and context
+
+- Primary files: `po/XX.po` for translations, `po/git.pot` for the source
+  template.
+- 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.
+- 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`.
+- Remove obsolete entries (marked with `#~`) since we no longer keep them.
+- 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.
+- Remove obsolete entries (marked with `#~`) since they are no longer kept.
+- 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.
+- Obsolete entries (marked with `#~`) should be removed since they are no
+  longer kept.
+- 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
+
+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`).
+
+
+### Example prompts for AI agents
+
+- Refer to @po/README.md to update translations in po/XX.po.
+- Refer to @po/README.md to review all translations in po/XX.po.
+
+
 [git-po-helper/README]: https://github.com/git-l10n/git-po-helper#readme
 [Documentation/SubmittingPatches]: Documentation/SubmittingPatches