From: Jiang Xin <worldhello.net@gmail•com>
To: Junio C Hamano <gitster@pobox•com>, Git List <git@vger•kernel.org>
Cc: "Jiang Xin" <worldhello.net@gmail•com>,
"Alexander Shopov" <ash@kambanaria•org>,
"Mikel Forcada" <mikel.forcada@gmail•com>,
"Ralf Thielow" <ralf.thielow@gmail•com>,
"Jean-Noël Avila" <jn.avila@free•fr>,
"Bagas Sanjaya" <bagasdotme@gmail•com>,
"Dimitriy Ryazantcev" <DJm00n@mail•ru>,
"Peter Krefting" <peter@softwolves•pp.se>,
"Emir SARI" <bitigchi@me•com>, "Arkadii Yakovets" <ark@cho•red>,
"Vũ Tiến Hưng" <newcomerminecraft@gmail•com>,
"Teng Long" <dyroneteng@gmail•com>,
"Yi-Jyun Pan" <pan93412@gmail•com>
Subject: [PATCH v2 2/5] docs(l10n): add AGENTS.md with optimized update-pot instructions
Date: Tue, 3 Mar 2026 23:33:29 +0800 [thread overview]
Message-ID: <5e23a45964fa86bf710d5e04396a574dc8882ef3.1772551123.git.worldhello.net@gmail.com> (raw)
In-Reply-To: <cover.1772551123.git.worldhello.net@gmail.com>
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 using the qwen model:
# Before: add the instruction to po/README.md; the prompt references
# po/README.md for execution
git-po-helper agent-test --runs=5 --agent=qwen update-pot \
--prompt="Update po/git.pot according to po/README.md"
# After: add the instruction to po/AGENTS.md; use builtin prompt
# that references po/AGENTS.md for 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 | After | 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 | After | 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
- Additional 11% reduction in turns and 17% in execution time
- More consistent behavior (turn range reduced from 3-7 to 3-3)
This change makes agent workflows more efficient and reduces API costs
by minimizing redundant LLM interactions.
Signed-off-by: Jiang Xin <worldhello.net@gmail•com>
---
po/AGENTS.md | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 92 insertions(+)
create mode 100644 po/AGENTS.md
diff --git a/po/AGENTS.md b/po/AGENTS.md
new file mode 100644
index 0000000000..1fcef9119a
--- /dev/null
+++ b/po/AGENTS.md
@@ -0,0 +1,92 @@
+# Instructions for AI Agents
+
+This file gives specific instructions for AI agents that perform
+housekeeping tasks for Git l10n. Use of AI is optional; many successful
+l10n teams work well without it.
+
+The section "Housekeeping tasks for localization workflows" documents the
+most commonly used housekeeping tasks.
+
+
+## Background knowledge for localization workflows
+
+Essential background for the workflows below; understand these concepts before
+performing any housekeeping tasks in this document.
+
+### Language code and notation (XX, ll, ll\_CC)
+
+XX is a placeholder for the language code. The code is either `ll` (ISO 639)
+or `ll_CC` (e.g. `de`, `zh_CN` for Simplified Chinese). It appears in the PO
+file's header entry metadata (e.g. `"Language: zh_CN\n"`) and is typically used
+as the filename: `po/XX.po`.
+
+
+### Header Entry
+
+Every PO file (`po/XX.po`) contains a special entry called the "header entry"
+at the beginning of the file. This entry has an empty `msgid` and contains
+metadata about the translation in its `msgstr`:
+
+```po
+msgid ""
+msgstr ""
+"Project-Id-Version: Git\n"
+"Report-Msgid-Bugs-To: Git Mailing List <git@vger•kernel.org>\n"
+"POT-Creation-Date: 2026-02-14 13:38+0800\n"
+"PO-Revision-Date: 2026-02-14 11:41+0800\n"
+"Last-Translator: Teng Long <dyroneteng@gmail•com>\n"
+"Language-Team: GitHub <https://github.com/dyrone/git/>\n"
+"Language: zh_CN\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+"X-Generator: Gtranslator 42.0\n"
+```
+
+**CRITICAL**: Do not modify the header's `msgstr` during translation. Extracted
+files (e.g. `po/l10n-pending.po`) include this header; preserve it exactly.
+
+The header provides: translation metadata (translator, language, dates);
+pluralization rules (`Plural-Forms`); encoding and MIME type; project/version.
+
+
+## Housekeeping tasks for localization workflows
+
+This section describes housekeeping tasks listed in the introduction. Read
+"Background knowledge for localization workflows" above before performing
+any task.
+
+
+### Task 1: Generating or updating po/git.pot
+
+When asked to "update po/git.pot" or similar requests:
+
+1. **Directly execute** the command `make po/git.pot` without checking
+ if the file exists beforehand.
+
+2. **Do not verify** the generated file after execution. Simply run the
+ command and consider the task complete.
+
+The command will handle all necessary steps including file creation or
+update automatically.
+
+
+## Human translators remain in control
+
+Git translation is human-driven; language team leaders and contributors are
+responsible for:
+
+- Understanding technical context of Git commands and messages
+- Making linguistic and cultural decisions for the target language
+- Maintaining translation quality and consistency
+- Ensuring translations follow Git l10n conventions and standards
+- Building and maintaining language glossaries
+- Reviewing and approving all changes before submission
+
+AI tools, if used, only accelerate routine tasks.
+
+AI-generated output should always be treated as rough drafts requiring human
+review, editing, and approval by someone who understands both the technical
+context and the target language. The best results come from combining AI
+efficiency with human judgment, cultural insight, and community engagement.
--
2.53.0.rc2.20.g532543fa46
next prev parent reply other threads:[~2026-03-03 15:33 UTC|newest]
Thread overview: 45+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-02-04 9:31 [RFC] Introducing AI Agents to Git Localization Jiang Xin
2026-02-04 11:58 ` Peter Krefting
2026-02-04 13:00 ` Michal Suchánek
2026-02-04 14:38 ` 依云
2026-02-05 2:06 ` Jiang Xin
2026-02-05 8:30 ` Michal Suchánek
2026-02-05 11:16 ` Jiang Xin
2026-02-05 13:18 ` Michal Suchánek
2026-02-05 1:04 ` Jiang Xin
2026-02-05 1:53 ` brian m. carlson
[not found] ` <0207CD38-C811-499D-AFA6-131B0CA825CD@gmail.com>
2026-02-05 12:54 ` Jiang Xin
2026-02-05 13:00 ` [RFC PATCH 1/2] l10n: add .gitattributes to simplify location filtering Jiang Xin
2026-02-05 20:07 ` Junio C Hamano
2026-02-05 13:00 ` [RFC PATCH 2/2] l10n: README: document AI assistant guidelines Jiang Xin
2026-02-05 20:35 ` Junio C Hamano
2026-02-06 2:38 ` Jiang Xin
2026-03-03 15:33 ` [PATCH v2 0/5] docs(l10n): AI agent instructions and workflow improvements Jiang Xin
2026-03-03 15:33 ` [PATCH v2 1/5] l10n: add .gitattributes to simplify location filtering Jiang Xin
2026-03-03 15:33 ` Jiang Xin [this message]
2026-03-12 2:11 ` [PATCH v2 2/5] docs(l10n): add AGENTS.md with optimized update-pot instructions Jiang Xin
2026-03-03 15:33 ` [PATCH v2 3/5] docs(l10n): add AI agent instructions for updating po/XX.po files Jiang Xin
2026-03-03 15:33 ` [PATCH v2 4/5] docs(l10n): add AI agent instructions for translating PO files Jiang Xin
2026-03-12 2:26 ` Jiang Xin
2026-03-03 15:33 ` [PATCH v2 5/5] docs(l10n): add AI agent instructions to review translations Jiang Xin
2026-03-12 2:34 ` Jiang Xin
2026-03-14 14:38 ` [PATCH v3 0/5] docs(l10n): AI agent instructions and workflow improvements Jiang Xin
2026-03-14 14:38 ` [PATCH v3 1/5] l10n: add .gitattributes to simplify location filtering Jiang Xin
2026-03-15 11:13 ` Johannes Sixt
2026-03-15 16:11 ` Junio C Hamano
2026-03-16 5:44 ` Jiang Xin
2026-03-16 3:21 ` Jiang Xin
2026-03-16 12:43 ` Johannes Sixt
2026-03-14 14:38 ` [PATCH v3 2/5] docs(l10n): add AGENTS.md with optimized update-pot instructions Jiang Xin
2026-03-14 14:38 ` [PATCH v3 3/5] docs(l10n): add AI agent instructions for updating po/XX.po files Jiang Xin
2026-03-14 14:38 ` [PATCH v3 4/5] docs(l10n): add AI agent instructions for translating PO files Jiang Xin
2026-03-14 14:38 ` [PATCH v3 5/5] docs(l10n): add AI agent instructions to review translations Jiang Xin
2026-03-16 23:54 ` [PATCH v4 0/5] docs(l10n): AI agent instructions and workflow improvements Jiang Xin
2026-03-16 23:54 ` [PATCH v4 1/5] l10n: add .gitattributes to simplify location filtering Jiang Xin
2026-03-16 23:54 ` [PATCH v4 2/5] docs(l10n): add AGENTS.md with optimized update-pot instructions Jiang Xin
2026-03-16 23:54 ` [PATCH v4 3/5] docs(l10n): add AI agent instructions for updating po/XX.po files Jiang Xin
2026-03-16 23:54 ` [PATCH v4 4/5] docs(l10n): add AI agent instructions for translating PO files Jiang Xin
2026-03-16 23:54 ` [PATCH v4 5/5] docs(l10n): add AI agent instructions to review translations Jiang Xin
2026-03-31 0:52 ` [PATCH v4 0/5] docs(l10n): AI agent instructions and workflow improvements Jiang Xin
2026-03-31 3:38 ` Junio C Hamano
2026-03-31 4:37 ` Jiang Xin
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=5e23a45964fa86bf710d5e04396a574dc8882ef3.1772551123.git.worldhello.net@gmail.com \
--to=worldhello.net@gmail$(echo .)com \
--cc=DJm00n@mail$(echo .)ru \
--cc=ark@cho$(echo .)red \
--cc=ash@kambanaria$(echo .)org \
--cc=bagasdotme@gmail$(echo .)com \
--cc=bitigchi@me$(echo .)com \
--cc=dyroneteng@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
--cc=jn.avila@free$(echo .)fr \
--cc=mikel.forcada@gmail$(echo .)com \
--cc=newcomerminecraft@gmail$(echo .)com \
--cc=pan93412@gmail$(echo .)com \
--cc=peter@softwolves$(echo .)pp.se \
--cc=ralf.thielow@gmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox