docs(l10n): add AI agent instructions for translating po/XX.po files

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

Author: jiangxin

po/README.md

@@ -495,6 +495,118 @@ The command will handle all necessary steps including generating
 "po/git.pot" and merging new translatable strings into "po/XX.po"
 automatically.
 
+### Translating po/XX.po
+
+When asked to translate "po/XX.po" or similar requests:
+
+**IMPORTANT: You must complete the translation of ALL untranslated and fuzzy
+entries. Do not stop early or report partial progress. Continue iterating
+through steps 1-6 until `po/XX.po.pending` is empty (contains no entries).**
+
+1. **Extract entries to translate**: Use `msgattrib` to extract
+   untranslated and fuzzy messages separately, then combine them. The
+   `--clear-fuzzy --empty` options for fuzzy entries clear their `msgstr`
+   values, treating them as untranslated entries:
+
+   ```shell
+   msgattrib --untranslated --no-obsolete po/XX.po -o po/XX.po.untranslated
+   msgattrib --only-fuzzy --no-obsolete --clear-fuzzy --empty po/XX.po -o po/XX.po.fuzzy
+   msgcat --use-first po/XX.po.untranslated po/XX.po.fuzzy -o po/XX.po.pending
+   ```
+
+   If `po/XX.po.pending` is empty, skip to step 7 (clean up) as the
+   translation is complete.
+
+2. **Truncate large po/XX.po.pending file**: If the `po/XX.po.pending` file
+   is too large to load at once, truncate it to process in batches:
+
+   2.1. **Find msgid line numbers**: Locate all `msgid` entry positions in
+        the file:
+
+        ```shell
+        grep -n "^msgid " po/XX.po.pending > msgid_lines.txt
+        ```
+
+   2.2. **Count total entries**: Check how many entries exist:
+
+        ```shell
+        TOTAL_ENTRIES=$(wc -l < msgid_lines.txt)
+        echo "Total entries: $TOTAL_ENTRIES"
+        ```
+
+   2.3. **Determine truncation point**: Find the line number immediately
+        before the 201st `msgid` entry (to keep the first 200 entries):
+
+        ```shell
+        # Get the line number of the 201st msgid
+        SPLIT_LINE=$(sed -n '201p' msgid_lines.txt | cut -d: -f1)
+        # Subtract 1 to cut before this msgid
+        SPLIT_LINE=$((SPLIT_LINE - 1))
+        ```
+
+   2.4. **Truncate the file**: Keep only the first 200 entries by truncating
+        at the determined line:
+
+        ```shell
+        head -n $SPLIT_LINE po/XX.po.pending > po/XX.po.pending.tmp
+        mv po/XX.po.pending.tmp po/XX.po.pending
+        ```
+
+   2.5. **If still too large**: If the truncated file is still too large,
+        use smaller batch sizes (try 100 entries, then 50, and so on):
+
+        ```shell
+        # For 100 entries
+        SPLIT_LINE=$(sed -n '101p' msgid_lines.txt | cut -d: -f1)
+        SPLIT_LINE=$((SPLIT_LINE - 1))
+        head -n $SPLIT_LINE po/XX.po.pending > po/XX.po.pending.tmp
+        mv po/XX.po.pending.tmp po/XX.po.pending
+        ```
+
+3. **Reference glossary**: Read the glossary section from the header of
+   `po/XX.po` (if present, before the first `msgid`) and use it for
+   consistent terminology during translation.
+
+4. **Translate entries**: Translate entries in `po/XX.po.pending` from English
+   (msgid) to the target language (msgstr), and write the translation results
+   directly into `po/XX.po.pending`:
+   - **Translation approach**: Translate the `po/XX.po.pending` file as a
+     whole, rather than translating entry by entry. If the file was truncated
+     in step 2, translate the current batch completely. **You must translate
+     ALL entries in the current batch** - do not stop after translating only
+     part of the batch.
+   - **For untranslated entries**: Translate the English `msgid` into the
+     target language in `msgstr`.
+   - **For fuzzy entries**: Since fuzzy entries have been cleared (empty
+     `msgstr`) in step 1, treat them the same as untranslated entries:
+     translate the English `msgid` into the target language in `msgstr`.
+     The `#, fuzzy` tag will be automatically removed when the entry is
+     merged back into `po/XX.po`.
+   - **For plural entries**: For entries with `msgid_plural`, provide all
+     required `msgstr[n]` forms based on the `Plural-Forms` header in
+     `po/XX.po`. The number of plural forms required depends on the target
+     language's plural rules.
+
+5. **Merge translated entries**: Merge the translated `po/XX.po.pending`
+   back into `po/XX.po`:
+
+   ```shell
+   msgcat --use-first po/XX.po.pending po/XX.po > po/XX.po.merged
+   mv po/XX.po.merged po/XX.po
+   ```
+
+6. **Repeat until complete**: **MANDATORY**: You MUST repeat steps 1-5
+   (extract, truncate if needed, translate, merge) until `po/XX.po.pending`
+   is completely empty. Do not report partial progress or stop early. The
+   task is only complete when there are zero untranslated and zero fuzzy
+   entries remaining in `po/XX.po`.
+
+7. **Clean up**: Only after confirming that `po/XX.po.pending` is empty
+   (no untranslated or fuzzy entries remain), remove all temporary files
+   (`po/XX.po.pending`, `po/XX.po.untranslated`, `po/XX.po.fuzzy`,
+   `msgid_lines.txt` if created). Do not clean up if there are still
+   untranslated or fuzzy entries remaining.
+
 
 [git-po-helper/README]: https://github.com/git-l10n/git-po-helper#readme
 [Documentation/SubmittingPatches]: Documentation/SubmittingPatches