From: Jiang Xin Date: Thu, 12 Mar 2026 02:26:06 GMT Subject: Re: [PATCH v2 4/5] docs(l10n): add AI agent instructions for translating PO files Message-ID: In-Reply-To: On Tue, Mar 3, 2026 at 11:34 PM Jiang Xin wrote: > +#### GETTEXT JSON format > + > +The **GETTEXT JSON** format is an internal format defined by `git-po-helper` > +for convenient batch processing of translation and related tasks by AI models. > +`git-po-helper msg-select`, `git-po-helper msg-cat`, and `git-po-helper compare` > +read and write this format. > + > +**Top-level structure**: > + > +```json > +{ > + "header_comment": "string", > + "header_meta": "string", > + "entries": [ /* array of entry objects */ ] > +} > +``` > + > +| Field | Description | > +|------------------|-------------------------------------------------------------------------------| > +| `header_comment` | Lines above the first `msgid ""` (comments, glossary). Directly concatenated. | > +| `header_meta` | Decoded `msgstr` of the header entry (Project-Id-Version, Plural-Forms, etc.).| > +| `entries` | List of PO entries. Order matches source. | > + > +**Entry object** (each element of `entries`): > + > +| Field | Type | Description | > +|-----------------|----------|-------------------------------------------------------| > +| `msgid` | string | Singular message ID. PO escapes encoded. | > +| `msgstr` | string | Singular message string. Empty for plural entries. | > +| `msgid_plural` | string | Plural form of msgid. Omit for non-plural. | > +| `msgstr_plural` | []string | Array of msgstr[0], msgstr[1], … Omit for non-plural. | > +| `comments` | []string | Comment lines (`#`, `#.`, `#:`, `#,`, etc.). | > +| `fuzzy` | bool | True if entry has fuzzy flag. | > +| `obsolete` | bool | True for `#~` obsolete entries. Omit if false. | The coexistence of msgstr (string) and msgstr_plural (string array) introduces redundancy and increases the risk of model generation errors. To resolve this, unify all translations into a single msgstr array in v3: - Single element: Represents the singular form (equivalent to PO msgstr or msgstr[0]). - Multiple elements: Represent plural forms in sequential order (msgstr[0], msgstr[1], …). > + > +**Example (single-line entry)**: > + > +```json > +{ > + "header_comment": "# Glossary:\\n# term1\\tTranslation 1\\n#\\n", > + "header_meta": "Project-Id-Version: git\\nContent-Type: text/plain; charset=UTF-8\\n", > + "entries": [ > + { > + "msgid": "Hello", > + "msgstr": "你好", "msgstr": ["你好"], > +**Example (plural entry)**: > + > +```json > +{ > + "msgid": "One file", > + "msgstr": "", > + "msgid_plural": "%d files", > + "msgstr_plural": ["一个文件", "%d 个文件"], "msgstr": ["一个文件", "%d 个文件"], > +6. **Repeat steps 1–5** until `po/l10n-pending.po` is empty (or does not exist). > + Do not stop early. > + > +7. **Final verification**: Some LLMs sometimes fail to follow instructions, skipping directly from Step 6 to Step 7. This issue can be resolved by renaming the Step 7 title to "7. **Only after loop exits**".