Skip to content

Commit 724b929

Browse files
jiangxinjiangxin
committed
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>
1 parent 7d530ac commit 724b929

File tree

1 file changed

+178
-1
lines changed

1 file changed

+178
-1
lines changed

‎po/AGENTS.md‎

Lines changed: 178 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ most commonly used housekeeping tasks:
1010
1. Generating or updating po/git.pot
1111
2. Updating po/XX.po
1212
3. Translating po/XX.po
13+
4. Reviewing translation quality
1314

1415

1516
## Background knowledge for localization workflows
@@ -728,6 +729,176 @@ and fuzzy entry; do not stop before the loop completes.
728729
```
729730

730731

732+
### Task 4: Review translation quality
733+
734+
Review may target the full `po/XX.po`, a specific commit, or changes since a
735+
commit. When asked to review, follow the steps below. **Note**: This task uses
736+
`git-po-helper compare`; if `git-po-helper` is not available, the task
737+
cannot be performed.
738+
739+
1. **Check for existing review**: Evaluate in order:
740+
741+
- If `po/review-input.po` does **not** exist, proceed to step 2 regardless
742+
of any other files (e.g., batch or JSON files).
743+
- If both `po/review-input.po` and `po/review-result.json` exist, go
744+
directly to the final step (Merge and summary) and display the report.
745+
Do **not** check for batch or other temporary files; no further review
746+
steps are needed.
747+
- If `po/review-input.po` exists but `po/review-result.json` does **not**
748+
exist, go to step 4 (Check batch files and select current batch) to
749+
continue the previous unfinished review.
750+
751+
2. **Extract entries**: Run `git-po-helper compare` with the desired range and
752+
redirect the output to `po/review-input.po`. Do not use `git show` or
753+
`git diff`—they can fragment or lose PO context (see "Comparing PO files
754+
for translation and review" under git-po-helper).
755+
756+
3. **Prepare review batches**: Run the script below to clean up any leftover
757+
files from previous reviews and split `po/review-input.po` into one or
758+
more `po/review-input-<N>.json` files (dynamic batch sizing). Run as a
759+
single script (define the function, then call it):
760+
761+
```shell
762+
review_split_batches () {
763+
min_batch_size=${1:-50}
764+
rm -f po/review-input-*.json
765+
rm -f po/review-result-*.json
766+
rm -f po/review-result.json
767+
rm -f po/review-output.po
768+
769+
if test ! -f po/review-output.po
770+
then
771+
cp po/review-input.po po/review-output.po
772+
fi
773+
774+
ENTRY_COUNT=$(grep -c '^msgid ' po/review-input.po 2>/dev/null || true)
775+
ENTRY_COUNT=$((ENTRY_COUNT > 0 ? ENTRY_COUNT - 1 : 0))
776+
777+
if test "$ENTRY_COUNT" -gt $min_batch_size
778+
then
779+
if test "$ENTRY_COUNT" -gt $((min_batch_size * 8))
780+
then
781+
NUM=$((min_batch_size * 2))
782+
elif test "$ENTRY_COUNT" -gt $((min_batch_size * 4))
783+
then
784+
NUM=$((min_batch_size + min_batch_size / 2))
785+
else
786+
NUM=$min_batch_size
787+
fi
788+
BATCH_COUNT=$(( (ENTRY_COUNT + NUM - 1) / NUM ))
789+
for i in $(seq 1 "$BATCH_COUNT")
790+
do
791+
START=$(((i - 1) * NUM + 1))
792+
END=$((i * NUM))
793+
if test "$END" -gt "$ENTRY_COUNT"
794+
then
795+
END=$ENTRY_COUNT
796+
fi
797+
if test "$i" -eq 1
798+
then
799+
git-po-helper msg-select --json --range "-$NUM" \
800+
po/review-input.po -o "po/review-input-$i.json"
801+
elif test "$END" -ge "$ENTRY_COUNT"
802+
then
803+
git-po-helper msg-select --json --range "$START-" \
804+
po/review-input.po -o "po/review-input-$i.json"
805+
else
806+
git-po-helper msg-select --json --range "$START-$END" \
807+
po/review-input.po -o "po/review-input-$i.json"
808+
fi
809+
done
810+
else
811+
git-po-helper msg-cat --json \
812+
-o po/review-input-1.json po/review-input.po
813+
fi
814+
}
815+
review_split_batches 50
816+
```
817+
818+
4. **Check batch files and select current batch**: If no batch files
819+
(`po/review-input-*.json`) exist, proceed to step 9. Otherwise, select the
820+
**first** remaining file (smallest batch index N) as the current batch. In
821+
steps 5–8, "current batch file" means `po/review-input-<N>.json`. This
822+
enables resuming after an unexpected stop.
823+
824+
5. **Read context**: Consult the "Background knowledge for localization
825+
workflows" section for PO format, JSON format, placeholder rules, and
826+
terminology. If the current batch file has a glossary in the
827+
`header_comment` field, add it to your context for consistent terminology.
828+
829+
6. **Review entries**:
830+
- Read the current batch file (`po/review-input-<N>.json`).
831+
- Do not review or modify the header entry (in PO format: empty `msgid`
832+
with metadata in `msgstr`; in JSON format: `header_comment` and
833+
`header_meta`).
834+
- For all other entries, check `msgstr` and `msgstr_plural` against the
835+
"Quality checklist" above.
836+
- After reviewing all entries in the current batch, save the report as
837+
described in the next step.
838+
839+
7. **Generate review report**:
840+
- Save the report for the current batch to `po/review-result-<N>.json`.
841+
See the "Review result JSON format" section below.
842+
- For each entry with issues, create an issue object: copy the original
843+
`msgid` to the `msgid` field; put the correct translation in
844+
`suggest_msgstr` (singular) or `suggest_msgstr_plural` (plural); write a
845+
summary of the issue in `description`; set `score` from 0 to 3 (3 =
846+
perfect, no issues found; 0 = critical, 1 = major, 2 = minor).
847+
- Include only entries with issues (score less than 3). Do **not** include
848+
entries with no issues (score 3).
849+
- Optionally provide inline suggestions or a human-readable report.
850+
851+
8. **Repeat review process**: After saving the report to
852+
`po/review-result-<N>.json`, delete `po/review-input-<N>.json`. Return to
853+
step 4 to review the next batch.
854+
855+
9. **Merge and summary**: Run the command below to merge all
856+
`po/review-result-*.json` files into `po/review-result.json`, optionally
857+
apply the result to `po/review-output.po`, and display the report. The
858+
command shows its output to the user. Do **not** open or read the result
859+
files; the user will refer to them as needed.
860+
861+
```shell
862+
git-po-helper agent-run --apply report
863+
```
864+
865+
**Review result JSON format**:
866+
867+
- `issues`: Array of issue objects. Each issue has:
868+
- `msgid` (and `msgid_plural` for plural): Original source text for reference.
869+
- `suggest_msgstr`: Correct translation for the singular form.
870+
- `suggest_msgstr_plural`: Array of correct translations for plural forms;
871+
`suggest_msgstr` is empty for plural entries.
872+
- `score`: 0–3 (see scale below).
873+
- `description`: Brief summary of the issue.
874+
- Score scale: 0 = critical (must fix before release), 1 = major (should fix),
875+
2 = minor (improve later), 3 = perfect.
876+
877+
878+
```json
879+
{
880+
"issues": [
881+
{
882+
"msgid": "commit",
883+
"msgid_plural": "",
884+
"suggest_msgstr": "提交",
885+
"suggest_msgstr_plural": [],
886+
"score": 0,
887+
"description": "Terminology error: 'commit' should be translated as '提交'",
888+
},
889+
{
890+
"msgid": "repository",
891+
"msgid_plural": "repositories",
892+
"suggest_msgstr": "",
893+
"suggest_msgstr_plural": ["仓库", "仓库"],
894+
"score": 2,
895+
"description": "Consistency issue: '版本库' and '仓库' are used interchangeably; suggest using '仓库' consistently",
896+
}
897+
]
898+
}
899+
```
900+
901+
731902
## Human translators remain in control
732903

733904
Git translation is human-driven; language team leaders and contributors are
@@ -740,7 +911,13 @@ responsible for:
740911
- Building and maintaining language glossaries
741912
- Reviewing and approving all changes before submission
742913

743-
AI tools, if used, only accelerate routine tasks.
914+
AI tools, if used, only accelerate routine tasks:
915+
916+
- First-draft translations for new or updated messages
917+
- Finding untranslated or fuzzy entries
918+
- Checking consistency with glossary and existing translations
919+
- Detecting technical errors (placeholders, formatting)
920+
- Reviewing against quality criteria
744921

745922
AI-generated output should always be treated as rough drafts requiring human
746923
review, editing, and approval by someone who understands both the technical

0 commit comments

Comments
 (0)