doc(l10n): add AI agent instructions to review translations

Add a new "Reviewing po/XX.po" section to po/AGENTS.md that provides
comprehensive guidance for AI agents to review translation files.

The review workflow leverages git-po-helper subcommands:

- git-po-helper compare: Extract new or changed entries between two PO
  file versions into a valid PO file for review. Supports multiple modes:
  * Compare HEAD with working tree (local changes)
  * Compare parent of commit with the commit (--commit)
  * Compare commit with working tree (--since)
  * Compare two arbitrary revisions (-r)

- git-po-helper msg-select: Split large review files into smaller batches
  by entry index range for manageable review sessions. Supports range
  formats like "-50" (first 50), "51-100", "101-" (from 101 to end).

The review procedure covers:
1. Extracting entries using git-po-helper compare
2. Handling large files with batch processing via git-po-helper msg-select
3. Step-by-step review against glossary and PO format rules
4. Outputting review reports in JSON format with issues and suggestions

This enables AI agents to conduct structured translation reviews for:
- Full file reviews
- Changes in a specific commit
- Changes since a specific commit

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

Author: jiangxin

po/AGENTS.md

@@ -10,6 +10,7 @@ most commonly used housekeeping tasks:
 1. Generating or updating po/git.pot
 2. Updating po/XX.po
 3. Translating po/XX.po
+4. Review translation quality
 
 
 ## Background knowledge for localization workflows
@@ -186,6 +187,64 @@ When `msgfmt` reports an error, it provides the line number where the error
 was detected. Use this information to locate and fix the issue.
 
 
+#### Extracting full context for review
+
+**This subsection is part of "Task 4: review translation quality".** Do not
+run it in isolation. Follow the full review flow strictly according to the
+steps in Task 4.
+
+Plain `git diff` or `git show` can fragment and lose PO context, or mistakenly
+treat the whole file as the review scope, which does not match the intended
+review. **You MUST** use `git-po-helper compare` to generate the source file
+for translation review (redirect output to a file):
+
+```shell
+# Review local changes (HEAD vs working tree)
+git-po-helper compare po/XX.po -o po/review.po
+
+# Review changes in a specific commit (parent vs commit)
+git-po-helper compare --commit <commit> po/XX.po -o po/review.po
+
+# Review changes since a commit (commit vs working tree)
+git-po-helper compare --since <commit> po/XX.po -o po/review.po
+
+# Review between two commits
+git-po-helper compare -r <commit1>..<commit2> po/XX.po -o po/review.po
+
+# Compare two worktree files
+git-po-helper compare po/XX-old.po po/XX-new.po -o po/review.po
+```
+
+**Options summary**
+
+| Option              | Meaning                                        |
+|---------------------|------------------------------------------------|
+| (none)              | Compare HEAD with working tree (local changes) |
+| `--commit <commit>` | Compare parent of commit with the commit       |
+| `--since <commit>`  | Compare commit with working tree               |
+| `-r x..y`           | Compare revision x with revision y             |
+| `-r x..`            | Compare revision x with working tree           |
+| `-r x`              | Compare parent of x with x                     |
+
+Output is empty when there are no new or changed entries; otherwise it
+includes a valid PO header.
+
+
+#### Splitting large PO file for review
+
+When the review file is too large, use `git-po-helper msg-select` to split by
+entry index: 0 = header (default; use `--no-header` to omit), 1,2,3,... =
+content entries. Ranges: `--range "1-50"`, `--range "-50"` (first 50),
+`--range "51-"` (from 51 to end).
+
+```shell
+git-po-helper msg-select --range "-50" po/review.po -o po/review-batch1.po
+git-po-helper msg-select --range "51-100" po/review.po -o po/review-batch2.po
+git-po-helper msg-select --range "101-" po/review.po -o po/review-batch3.po
+git-po-helper msg-select --range "1-50" --no-header po/review.po -o po/review-fragment.po
+```
+
+
 ### Quality checklist
 
 - **Accuracy**: Faithful to original meaning; no omissions or distortions.
@@ -520,6 +579,146 @@ For the full schema reference, see the "GETTEXT JSON File Format (Reference)"
 section in the msg-select JSON design document.
 
 
+### Task 4: Review translation quality
+
+Review can target the full `po/XX.po`, a specific commit, or changes since a
+commit. When asked to review, follow the steps below. **Note**: Review uses
+`git-po-helper compare`; if `git-po-helper` is not available, this task
+cannot be performed.
+
+1. **Check for existing review**: Run in order:
+
+   - If `po/review.po` does **not** exist, go to step 2 regardless of any other
+     files (e.g. batch or JSON files).
+   - If both `po/review.po` and `po/review.json` exist, go directly to the
+     final step (Merge and summary) and display the report. Do **not** check
+     for batch or other temporary files; no further review steps are needed.
+   - If `po/review.po` exists but `po/review.json` does **not** exist, go to
+     step 4 (Check batch files and select current batch) to continue the
+     previous unfinished review.
+
+2. **Extract entries**: Run `git-po-helper compare` with the desired range and
+   redirect output to `po/review.po`. Do not use `git show` or `git diff`—they
+   can fragment or lose PO context, or treat the whole file as the review scope
+   (see "Extracting full context for review" above).
+
+3. **Prepare review batches**: Run the script below to clean up any leftover
+   files from previous reviews and split `po/review.po` into one or multiple
+   `po/review-batch-<N>.po` files (dynamic batch sizing). Run as a single
+   script (define the function, then call it):
+
+   ```shell
+   review_split_batches () {
+       min_batch_size=${1:-50}
+       rm -f po/review-batch-*.po
+       rm -f po/review-batch-*.json
+       rm -f po/review.json
+
+       ENTRY_COUNT=$(grep -c '^msgid ' po/review.po 2>/dev/null || true)
+       ENTRY_COUNT=$((ENTRY_COUNT > 0 ? ENTRY_COUNT - 1 : 0))
+
+       if test "$ENTRY_COUNT" -gt $((min_batch_size * 2))
+       then
+           if test "$ENTRY_COUNT" -gt $((min_batch_size * 8))
+           then
+               NUM=$((min_batch_size * 2))
+           elif test "$ENTRY_COUNT" -gt $((min_batch_size * 4))
+           then
+               NUM=$((min_batch_size + min_batch_size / 2))
+           else
+               NUM=$min_batch_size
+           fi
+           BATCH_COUNT=$(( (ENTRY_COUNT + NUM - 1) / NUM ))
+           for i in $(seq 1 "$BATCH_COUNT")
+           do
+               START=$(((i - 1) * NUM + 1))
+               END=$((i * NUM))
+               if test "$END" -gt "$ENTRY_COUNT"
+               then
+                   END=$ENTRY_COUNT
+               fi
+               if test "$i" -eq 1
+               then
+                   git-po-helper msg-select --range "-$NUM" po/review.po -o "po/review-batch-$i.po"
+               elif test "$END" -ge "$ENTRY_COUNT"
+               then
+                   git-po-helper msg-select --range "$START-" po/review.po -o "po/review-batch-$i.po"
+               else
+                   git-po-helper msg-select --range "$START-$END" po/review.po -o "po/review-batch-$i.po"
+               fi
+           done
+       else
+           cp po/review.po po/review-batch-1.po
+       fi
+   }
+   review_split_batches 50
+   ```
+
+4. **Check batch files and select current batch**: If no `po/review-batch-*.po`
+   exist, proceed to step 9. Otherwise take the **first** remaining file
+   (smallest <N>) as the current batch; in steps 5–8 "current batch file"
+   means `po/review-batch-<N>.po`. Enables resume after an unexpected stop.
+
+5. **Read context**: Use "Background knowledge for localization workflows"
+   for PO format, placeholder rules, and terminology. If the current batch
+   file has a glossary section, add it to your context.
+
+6. **Review entries**:
+   - Do not review or modify the header entry (empty `msgid`, metadata in
+     `msgstr`).
+   - For all other entries in the current batch file, check against "Quality
+     checklist" above.
+   - Apply corrections to `po/review.po` (not the batch file); the human
+     translator decides whether to apply them to `po/XX.po`.
+   - **Do NOT** remove `po/review.po` or `po/*.json`.
+
+7. **Generate review report**:
+   - Save the report for the current batch to `po/review-batch-<N>.json`.
+   - Use the review JSON format below.
+   - Only include entries with issues you found, perfect entries with score 3
+     should not be included.
+   - Optionally provide inline suggestions or a human-readable report.
+
+8. **Repeat or finish**: After saving the JSON, delete
+   `po/review-batch-<N>.po`. If no `po/review-batch-*.po` remain, proceed to
+   step 9; otherwise repeat from step 4.
+
+9. **Merge and summary**: Run `git-po-helper agent-run report` to merge all
+   `po/review-batch-*.json` into `po/review.json` and display the result. Show
+   the command output to the user. Do **not** open or read any JSON files; the
+   user will refer to them as needed.
+
+   ```shell
+   git-po-helper agent-run report
+   ```
+
+**Review JSON format.** Use the following structure:
+
+```json
+{
+  "issues": [
+    {
+      "msgid": "commit",
+      "msgstr": "承诺",
+      "score": 0,
+      "description": "术语错误：'commit'应译为'提交'",
+      "suggestion": "提交"
+    },
+    {
+      "msgid": "repository",
+      "msgstr": "仓库",
+      "score": 2,
+      "description": "一致性问题：其他地方使用'版本库'",
+      "suggestion": "版本库"
+    }
+  ]
+}
+```
+
+- `issues`: Array of issues. Each issue: `msgid`, `msgstr`, `score`, `description`, `suggestion`.
+- `score`: 0 = critical (must fix before release), 1 = major (should fix), 2 = minor (improve later), 3 = perfect.
+
+
 ## Human translators remain in control
 
 Git translation is human-driven; language team leaders and contributors are
@@ -532,7 +731,13 @@ responsible for:
 - Building and maintaining language glossaries
 - Reviewing and approving all changes before submission
 
-AI tools, if used, only accelerate routine tasks.
+AI tools, if used, only accelerate routine tasks:
+
+- First-draft translations for new or updated messages
+- Finding untranslated or fuzzy entries
+- Checking consistency with glossary and existing translations
+- Detecting technical errors (placeholders, formatting)
+- Reviewing against quality criteria
 
 AI-generated output should always be treated as rough drafts requiring human
 review, editing, and approval by someone who understands both the technical