Re: [PATCH v2 4/5] docs(l10n): add AI agent instructions for translating PO files

From: Jiang Xin <worldhello.net@gmail.com>
Date: Mar 12, 2026, 02:26 UTC
Message-ID: <CANYiYbGhZVCmYPN6kBeP2UpZMjzMFEetNCaefCf1LAWQPezhow@mail.gmail.com>
In-Reply-To: <d6785db1dfedeccca1cddc17d8c95b99eb266500.1772551123.git.worldhello.net@gmail.com>

On Tue, Mar 3, 2026 at 11:34 PM Jiang Xin <worldhello.net@gmail.com> wrote:

Show 34 quoted lines

> +#### 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], …).

Show 11 quoted lines

> +
> +**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": ["你好"],

Show 8 quoted lines

> +**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**".