@matheusbsbs / matheus-bagliano / commits / 66dd9b2b94

l10n: docs: add AGENTS.md with update POT instructions

Add a new documentation file po/AGENTS.md that provides agent-specific instructions for generating or updating po/git.pot, separating them from the general po/README.md. This separation allows for more targeted optimization of AI agent workflows. Performance evaluation with the Qwen model: # Before: No agent-specific instructions; use po/README.md for # reference. git-po-helper agent-test --runs=5 --agent=qwen update-pot \ --prompt="Update po/git.pot according to po/README.md" # Phase 1: add the instructions to po/README.md; the prompt # references po/README.md during execution git-po-helper agent-test --runs=5 --agent=qwen update-pot \ --prompt="Update po/git.pot according to po/README.md" # Phase 2: add the instructions to po/AGENTS.md; use the built-in # prompt that references po/AGENTS.md during execution git-po-helper agent-test --runs=5 --agent=qwen update-pot Benchmark results (5-run average): Phase 1 - Optimizing po/README.md: | Metric | Before | Phase 1 | Improvement | |-------------|---------|---------|-------------| | Turns | 17 | 5 | -71% | | Exec. time | 34s | 14s | -59% | | Turn range | 3-36 | 3-7 | | | Time range | 10s-59s | 9s-19s | | Phase 2 - Adding po/AGENTS.md (further optimization): | Metric | Before | Phase 2 | Improvement | |-------------|---------|---------|-------------| | Turns | 17 | 3 | -82% | | Exec. time | 34s | 8s | -76% | | Turn range | 3-36 | 3-3 | | | Time range | 10s-59s | 6s-9s | | Separating agent-specific instructions into AGENTS.md provides: - More focused and concise instructions for AI agents - Cleaner README.md for human readers - An additional 11% reduction in turns and 17% reduction in execution time - More consistent behavior (turn range reduced from 3-7 to 3-3) Signed-off-by: Jiang Xin <worldhello.net@gmail.com>

Jiang Xin committed Feb 14, 2026 at 14:08 UTC 66dd9b2b94e25769448990a2521ad3fd9da3c515
1 file changed +70
po/AGENTS.md new
+70
@@ -0,0 +1,70 @@
1 +# Instructions for AI Agents
2 +
3 +This file gives specific instructions for AI agents that perform
4 +housekeeping tasks for Git l10n. Use of AI is optional; many successful
5 +l10n teams work well without it.
6 +
7 +The section "Housekeeping tasks for localization workflows" documents the
8 +most commonly used housekeeping tasks.
9 +
10 +
11 +## Background knowledge for localization workflows
12 +
13 +Essential background for the workflows below; understand these concepts before
14 +performing any housekeeping tasks in this document.
15 +
16 +### Language code and notation (XX, ll, ll\_CC)
17 +
18 +**XX** is a placeholder for the language code: either `ll` (ISO 639) or
19 +`ll_CC` (e.g. `de`, `zh_CN`). It appears in the PO file header metadata
20 +(e.g. `"Language: zh_CN\n"`) and is typically used to name the PO file:
21 +`po/XX.po`.
22 +
23 +
24 +### Header Entry
25 +
26 +The **header entry** is the first entry in every `po/XX.po`. It has an empty
27 +`msgid`; translation metadata (project, language, plural rules, encoding, etc.)
28 +is stored in `msgstr`, as in this example:
29 +
30 +```po
31 +msgid ""
32 +msgstr ""
33 +"Project-Id-Version: Git\n"
34 +"Language: zh_CN\n"
35 +"MIME-Version: 1.0\n"
36 +"Content-Type: text/plain; charset=UTF-8\n"
37 +"Content-Transfer-Encoding: 8bit\n"
38 +"Plural-Forms: nplurals=2; plural=(n != 1);\n"
39 +```
40 +
41 +**CRITICAL**: Do not edit the header's `msgstr` while translating. It holds
42 +metadata only and must be left unchanged.
43 +
44 +
45 +## Housekeeping tasks for localization workflows
46 +
47 +For common housekeeping tasks, follow the steps in the matching subsection
48 +below.
49 +
50 +
51 +### Task 1: Generating or updating po/git.pot
52 +
53 +When asked to generate or update `po/git.pot` (or the like):
54 +
55 +1. **Directly execute** the command `make po/git.pot` without checking
56 + if the file exists beforehand.
57 +
58 +2. **Do not verify** the generated file after execution. Simply run the
59 + command and consider the task complete.
60 +
61 +
62 +## Human translators remain in control
63 +
64 +Git translation is human-driven; language team leaders and contributors are
65 +responsible for maintaining translation quality and consistency.
66 +
67 +AI-generated output should always be treated as drafts that must be reviewed
68 +and approved by someone who understands both the technical context and the
69 +target language. The best results come from combining AI efficiency with human
70 +judgment, cultural insight, and community engagement.