From bce7d1d30cbf4b0c46f1e7d75adc11a4335db5b1 Mon Sep 17 00:00:00 2001 From: Will Miao Date: Sun, 30 Aug 2026 16:28:53 +0800 Subject: [PATCH] =?UTF-8?q?docs(i18n):=20resolve=20R1=20vs=20R8/=C2=A77=20?= =?UTF-8?q?contradiction=20on=20proactive=20translation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit R1 instructed agents to "translate the newly added keys in every locale" right after syncing, while R8 and §7 make [TODO: Translate] placeholders the sanctioned end state during feature development until the feature owner explicitly asks for translations. Reword R1 and the AGENTS.md Localization section to say stop after syncing and never translate proactively. --- AGENTS.md | 5 +++++ docs/i18n-translation-guidelines.md | 4 +++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index ac145471..5db5eae7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,6 +72,11 @@ python scripts/sync_translation_keys.py Locale files are in `locales/` (en, zh-CN, zh-TW, ja, ko, fr, de, es, ru, he). +After adding keys to `en.json` and syncing, **stop**: the `[TODO: Translate]` placeholders in +the other locales are the expected end state during feature development. Do NOT translate +proactively — translate only when the feature owner explicitly asks (see +`docs/i18n-translation-guidelines.md` §7). + **Before translating anything, read `docs/i18n-translation-guidelines.md`** — it defines the term conventions (e.g. "Recipe" stays untranslated in French, 配方 in Chinese; model-type and brand names are never translated), per-locale preferred renderings, placeholder rules, and diff --git a/docs/i18n-translation-guidelines.md b/docs/i18n-translation-guidelines.md index 1bedd299..bcc124a0 100644 --- a/docs/i18n-translation-guidelines.md +++ b/docs/i18n-translation-guidelines.md @@ -23,7 +23,9 @@ Locales: `en`, `zh-CN`, `zh-TW`, `ja`, `ko`, `fr`, `de`, `es`, `ru`, `he` (RTL). same nested key set. `tests/i18n/test_i18n.py` enforces this. - When a new UI string is added to `en.json`, run `python scripts/sync_translation_keys.py` (adds the missing keys to all locales with - placeholder copies), then translate the newly added keys in every locale. + `[TODO: Translate]` placeholder copies) — **then stop**. Do NOT translate proactively: + placeholders are the expected end state during feature development, and translations are + filled in only when the feature owner explicitly asks (workflow details in §7). - Never reorder, re-indent, or reformat a locale file "for tidiness". The sync script preserves formatting; manual reformatting creates noisy diffs.