Skip to content

Commit c337a71

Browse files
jiangxinjiangxin
committed
patches
Signed-off-by: Jiang Xin <worldhello.net@gmail.com>
1 parent 00fb14c commit c337a71

6 files changed

+1578
-0
lines changed

‎v2-0000-cover-letter.patch‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
From d7a7a07acdcf15520019fc58be5e6a1a1e24791a Mon Sep 17 00:00:00 2001
2+
Message-ID: <cover.1772551123.git.worldhello.net@gmail.com>
3+
In-Reply-To: <CANYiYbFM9+4xGmeBRNCC6VyW9EzjEFxEWHDNnOVhJNM73Ga_FA@mail.gmail.com>
4+
References: <CANYiYbFM9+4xGmeBRNCC6VyW9EzjEFxEWHDNnOVhJNM73Ga_FA@mail.gmail.com>
5+
From: Jiang Xin <worldhello.net@gmail.com>
6+
Date: Tue, 3 Mar 2026 23:18:43 +0800
7+
Subject: [PATCH v2 0/5] docs(l10n): AI agent instructions and workflow improvements
8+
MIME-Version: 1.0
9+
Content-Type: text/plain; charset=UTF-8
10+
Content-Transfer-Encoding: 8bit
11+
To: Junio C Hamano <gitster@pobox.com>,
12+
Git List <git@vger.kernel.org>
13+
Cc: Alexander Shopov <ash@kambanaria.org>,
14+
Mikel Forcada <mikel.forcada@gmail.com>,
15+
Ralf Thielow <ralf.thielow@gmail.com>,
16+
Jean-Noël Avila <jn.avila@free.fr>,
17+
Bagas Sanjaya <bagasdotme@gmail.com>,
18+
Dimitriy Ryazantcev <DJm00n@mail.ru>,
19+
Peter Krefting <peter@softwolves.pp.se>,
20+
Emir SARI <bitigchi@me.com>,
21+
Arkadii Yakovets <ark@cho.red>,
22+
Vũ Tiến Hưng <newcomerminecraft@gmail.com>,
23+
Teng Long <dyroneteng@gmail.com>,
24+
Yi-Jyun Pan <pan93412@gmail.com>
25+
26+
## Introduction
27+
28+
This series introduces AI agent instructions for Git localization (l10n) workflows
29+
to help localization contributors quickly complete drafts and use AI to check
30+
translation quality. The changes focus on:
31+
32+
1. Separating agent-specific documentation into po/AGENTS.md for targeted
33+
optimization of AI-assisted workflows
34+
2. Providing step-by-step instructions for update-pot, update-po, translation,
35+
and review tasks
36+
3. Simplifying location filtering for PO file commits via .gitattributes
37+
38+
AI-assisted translation is optional; many successful l10n teams work well without
39+
it. When used, AI output serves as reference only—human contributors must review
40+
and approve before submission.
41+
42+
## Performance summary
43+
44+
| Task | Before | After | Improvement |
45+
|-------------|---------------|--------------|---------------------------------|
46+
| update-pot | 17 turns, 34s | 3 turns, 8s | -82% turns, -76% time |
47+
| update-po | 22 turns, 38s | 4 turns, 9s | -82% turns, -76% time |
48+
| translate | 86 turns | 56 turns | -35% turns (git-po-helper flow) |
49+
| review | N/A | 96/100 score | New workflow documented |
50+
51+
These improvements reduce API costs and make agent workflows more efficient while
52+
maintaining human oversight of translation quality.
53+
54+
## Testing
55+
56+
All changes have been evaluated with the qwen model via git-po-helper agent-test
57+
and agent-run. The po/AGENTS.md instructions are designed to work with coding
58+
tools that support file references (e.g., "Translate po/zh_CN.po by referring to
59+
@po/AGENTS.md").
60+
61+
## Changes
62+
63+
Jiang Xin (5):
64+
l10n: add .gitattributes to simplify location filtering
65+
docs(l10n): add AGENTS.md with optimized update-pot instructions
66+
docs(l10n): add AI agent instructions for updating po/XX.po files
67+
docs(l10n): add AI agent instructions for translating PO files
68+
docs(l10n): add AI agent instructions to review translations
69+
70+
po/.gitattributes | 36 ++
71+
po/AGENTS.md | 941 ++++++++++++++++++++++++++++++++++++++++++++++
72+
po/README.md | 70 ++--
73+
3 files changed, 1015 insertions(+), 32 deletions(-)
74+
create mode 100644 po/.gitattributes
75+
create mode 100644 po/AGENTS.md

‎v2-0001-l10n-add-.gitattributes-to-simplify-location-filt.patch‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
From ed04d37535991a1b0e27dc5bc20ec29942e8299e Mon Sep 17 00:00:00 2001
2+
Message-ID: <ed04d37535991a1b0e27dc5bc20ec29942e8299e.1772551123.git.worldhello.net@gmail.com>
3+
In-Reply-To: <cover.1772551123.git.worldhello.net@gmail.com>
4+
References: <CANYiYbFM9+4xGmeBRNCC6VyW9EzjEFxEWHDNnOVhJNM73Ga_FA@mail.gmail.com>
5+
<cover.1772551123.git.worldhello.net@gmail.com>
6+
From: Jiang Xin <worldhello.net@gmail.com>
7+
Date: Wed, 4 Feb 2026 11:39:22 +0800
8+
Subject: [PATCH v2 1/5] l10n: add .gitattributes to simplify location
9+
filtering
10+
To: Junio C Hamano <gitster@pobox.com>,
11+
Git List <git@vger.kernel.org>
12+
Cc: Alexander Shopov <ash@kambanaria.org>,
13+
Mikel Forcada <mikel.forcada@gmail.com>,
14+
Ralf Thielow <ralf.thielow@gmail.com>,
15+
Jean-Noël Avila <jn.avila@free.fr>,
16+
Bagas Sanjaya <bagasdotme@gmail.com>,
17+
Dimitriy Ryazantcev <DJm00n@mail.ru>,
18+
Peter Krefting <peter@softwolves.pp.se>,
19+
Emir SARI <bitigchi@me.com>,
20+
Arkadii Yakovets <ark@cho.red>,
21+
Vũ Tiến Hưng <newcomerminecraft@gmail.com>,
22+
Teng Long <dyroneteng@gmail.com>,
23+
Yi-Jyun Pan <pan93412@gmail.com>
24+
25+
To simplify the location filtering process for l10n contributors when
26+
committing po/XX.po files, add the filter attributes for selected PO
27+
files to the repository. This ensures all contributors automatically
28+
get the same filter configuration without manual setup in
29+
.git/info/attributes.
30+
31+
The filter attribute is only applied to specific PO files that have
32+
been properly prepared. Files without the filter attribute fall into
33+
two categories:
34+
35+
- Legacy files that lack maintenance and still contain location
36+
comments that have not been cleaned up
37+
- Files whose formatting (such as line wrapping) differs from the
38+
output of msgcat processing
39+
40+
To avoid discrepancies between the filtered blob in the index and the
41+
unfiltered working tree for these files, the filter attribute is not
42+
applied to them.
43+
44+
Contributors still need to manually define the filter drivers using
45+
git-config as documented in po/README.md.
46+
47+
Additionally, po/README.md has been reorganized: the content of handling
48+
location-less PO file content has been moved from the "Updating a XX.po
49+
file" section to a separate "Preparing a XX.po file for commit" section.
50+
This prevents AI agents from introducing unrelated operations when
51+
updating PO files.
52+
53+
Signed-off-by: Jiang Xin <worldhello.net@gmail.com>
54+
---
55+
po/.gitattributes | 36 ++++++++++++++++++++++++
56+
po/README.md | 70 +++++++++++++++++++++++++----------------------
57+
2 files changed, 74 insertions(+), 32 deletions(-)
58+
create mode 100644 po/.gitattributes
59+
60+
diff --git a/po/.gitattributes b/po/.gitattributes
61+
new file mode 100644
62+
index 0000000000..7100b7050e
63+
--- /dev/null
64+
+++ b/po/.gitattributes
65+
@@ -0,0 +1,36 @@
66+
+# Git Attributes for PO Files
67+
+#
68+
+# This file configures Git filters to automatically strip location information
69+
+# from PO files when committing, producing cleaner diffs and saving repository
70+
+# space.
71+
+#
72+
+# Two filter types are used:
73+
+# 1. gettext-no-file-no-location: Strips both filenames and line numbers
74+
+# (e.g., removes "#: main.c:123" entirely)
75+
+# 2. gettext-no-location: Preserves filenames but removes line numbers, which
76+
+# requires gettext 0.20 or higher
77+
+# (e.g., "#: main.c:123" becomes "#: main.c")
78+
+#
79+
+# See `po/README.md` for instructions on setting up the required filter drivers.
80+
+
81+
+# Do not configure default attributes for `*.po` files, as this would cause
82+
+# differences between the filtered blob stored in the index and the unfiltered
83+
+# working tree version for legacy, unmaintained PO files.
84+
+
85+
+# Languages that strip both filenames and line numbers
86+
+bg.po filter=gettext-no-file-no-location
87+
+de.po filter=gettext-no-file-no-location
88+
+#es.po filter=gettext-no-file-no-location
89+
+fr.po filter=gettext-no-file-no-location
90+
+#ga.po filter=gettext-no-file-no-location
91+
+#ru.po filter=gettext-no-file-no-location
92+
+sv.po filter=gettext-no-file-no-location
93+
+tr.po filter=gettext-no-file-no-location
94+
+uk.po filter=gettext-no-file-no-location
95+
+vi.po filter=gettext-no-file-no-location
96+
+
97+
+# Languages that preserve filenames but strip line numbers
98+
+#ca.po filter=gettext-no-location
99+
+id.po filter=gettext-no-location
100+
+zh_CN.po filter=gettext-no-location
101+
+zh_TW.po filter=gettext-no-location
102+
diff --git a/po/README.md b/po/README.md
103+
index ec08aa24ad..79757d4c21 100644
104+
--- a/po/README.md
105+
+++ b/po/README.md
106+
@@ -159,38 +159,6 @@ It will:
107+
and these location lines will help translation tools to locate
108+
translation context easily.
109+
110+
-Once you are done testing the translation (see below), it's better
111+
-to commit a location-less "po/XX.po" file to save repository space
112+
-and make a user-friendly patch for review.
113+
-
114+
-To save a location-less "po/XX.po" automatically in repository, you
115+
-can:
116+
-
117+
-First define a new attribute for "po/XX.po" by appending the following
118+
-line in ".git/info/attributes":
119+
-
120+
-```
121+
-/po/XX.po filter=gettext-no-location
122+
-```
123+
-
124+
-Then define the driver for the "gettext-no-location" clean filter to
125+
-strip out both filenames and locations from the contents as follows:
126+
-
127+
-```shell
128+
-git config --global filter.gettext-no-location.clean \
129+
- "msgcat --no-location -"
130+
-```
131+
-
132+
-For users who have gettext version 0.20 or higher, it is also possible
133+
-to define a clean filter to preserve filenames but not locations:
134+
-
135+
-```shell
136+
-git config --global filter.gettext-no-location.clean \
137+
- "msgcat --add-location=file -"
138+
-```
139+
-
140+
-You're now ready to ask the l10n coordinator to pull from you.
141+
-
142+
143+
## Fuzzy translation
144+
145+
@@ -229,6 +197,44 @@ git-po-helper check-commits <rev-list-opts>
146+
```
147+
148+
149+
+## Preparing a "XX.po" file for commit
150+
+
151+
+Once you are done testing the translation, it's better to commit a
152+
+location-less "po/XX.po" file to save repository space and make a
153+
+user-friendly patch for review.
154+
+
155+
+To save a location-less "po/XX.po" automatically in repository, you
156+
+can:
157+
+
158+
+First, check which filter is configured for your "po/XX.po" file:
159+
+
160+
+```
161+
+git check-attr filter po/XX.po
162+
+```
163+
+
164+
+The filter configuration is defined in the "po/.gitattributes" file.
165+
+
166+
+Then define the driver for the filter. Most languages use the
167+
+"gettext-no-file-no-location" clean filter, which strips out both filenames and
168+
+locations from the comments. To set this up, run the following command:
169+
+
170+
+```shell
171+
+git config --global filter.gettext-no-file-no-location.clean \
172+
+ "msgcat --no-location -"
173+
+```
174+
+
175+
+Some languages use the "gettext-no-location" clean filter, which preserves
176+
+filenames but not locations. For these, install gettext version 0.20 or higher
177+
+and setup the driver as below:
178+
+
179+
+```shell
180+
+git config --global filter.gettext-no-location.clean \
181+
+ "msgcat --add-location=file -"
182+
+```
183+
+
184+
+You're now ready to ask the l10n coordinator to pull from you.
185+
+
186+
+
187+
## Marking strings for translation
188+
189+
(This is done by the core developers).
190+
--
191+
2.53.0.rc2.20.g532543fa46
192+

0 commit comments

Comments
 (0)