i18n

Locale Management (detail)

Extracted verbatim from AGENTS.md — the detailed half of "Locale management". AGENTS.md keeps the commands and the add/modify-key rules.

scripts/i18n.py (stdlib only) is the single entry point — the older sync_locales.py / check_translations.py are retired:

python3 scripts/i18n.py audit                 # scan all _m()/__MSG_*__ references vs en definitions (undefined/unused keys)
python3 scripts/i18n.py missing               # per-locale report vs en baseline: missing / [TODO] / suspect-equal-to-en
python3 scripts/i18n.py translate --locale fr --apply   # LLM-translate a locale's pending keys, write back in key order
python3 scripts/i18n.py verify                # gate: key-set alignment + no [TODO] + $placeholder$ integrity + menu-length warnings

文件格式契约（2026-08-26 起强制）

每个 _locales/<lang>/messages.json 必须满足：key 字母序、2 空格缩进、 UTF-8 明文、文件末尾换行。43 个 locale 共用同一排序（以 en 为基准， sort_keys=True 的字典序）——新增/修改 key 一律按字母序插入到正确位置， 禁止追加到文件尾部（旧做法导致各语种 key 序随插入历史漂移，diff 不可读、 合并冲突频繁）。translate --apply 与 verify 均保持该顺序；手工编辑后 用 json.dump(d, f, ensure_ascii=False, indent=2, sort_keys=True) 归一化核对 （或运行 python3 scripts/i18n.py verify + git diff 目检）再提交。CI 的 i18n.py missing / verify 门禁只查键集与占位符完整性，不查排序——排序 靠本契约人工把关。

Key 增改流程

All 43 locales currently hold the same 685 keys as the en baseline — keys without a real translation carry [TODO:key] placeholder messages. When adding keys: translate en + zh_CN for real, insert [TODO:key] placeholders in place (right after their en neighbor) into the other locales — do NOT reorder keys — then check with python3 scripts/i18n.py missing. When modifying the text of an existing key the same sync is required — update en + zh_CN for real, then force re-translation in the other locales by overwriting the key's message with the [TODO:key] placeholder in each of them (already-translated text is invisible to translate: it only fills missing/[TODO:] keys, so a stale-but-translated key would silently keep its old wording) — then run the same translate --apply + verify flow below. TODO placeholders are only an intermediate state, never a deliverable one: before every commit/packaging run python3 scripts/i18n.py translate --apply to fill them (LLM endpoint from the git-ignored .env), and the release gate is python3 scripts/i18n.py verify at 0 errors — do not treat a verify failure caused by leftover [TODO:] as expected, and do not mistake audit (code-reference check, blind to translation state) for this gate. translate fills every pending key of a locale in one batched run (40 keys/request) against a chat LLM — configure via env or a git-ignored repo-root .env: VBM_LLM_API_KEY required, VBM_LLM_BASE_URL (default https://api.moonshot.cn/v1), VBM_LLM_MODEL (default kimi-k2-0905-preview) and VBM_LLM_API_TYPE (openai default, or anthropic_messages for Anthropic-style endpoints like DeepSeek's) optional. The built-in Chinese prompt explains the bookmark-manager context and per-category constraints. 2026-08-28 审阅轮细化：prompt 现携带 (a) 术语表 —— STAGING_TERMS（staging 在每个语言的定案译法，人工维护，新增/改译法时同步那处 dict）与 tab group/separator/bookmark 的术语律；(b) 输出语言断言（严禁第三语言混入）；(c) 同批一致性要求；(d) 大小写规则（非英语句式大小写，禁 Title Case）；(e) zh_TW/zh_HK 字形叮嘱（SCRIPT_NOTES，严禁简体字形与大陆用语）；(f) 菜单字符预算前移——menu 类条目带 budget 字段（35 拉丁 / 18 CJK），首译即达标。dry-run is the default, --apply writes back preserving each file's key order and placeholders structure. verify adds two machine checks from the same round: 串语检测（非 CJK 语系译文含汉字即 ERROR）与简繁检测（zh_TW/zh_HK 含简体专属字形即 ERROR），plus the menu-length warnings (now clean at 0) with --fix for LLM shortening.