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.