| 1 | # Locale agent guidance |
| 2 | |
| 3 | `en.json` is the reference pack. The locale registry defines which other packs |
| 4 | are complete; do not treat an old assertion as product authority when the |
| 5 | registry or localization design has intentionally changed. |
| 6 | |
| 7 | For every new string: |
| 8 | |
| 9 | 1. Add the `MessageId` variant, `ALL_MESSAGE_IDS` entry, and English key. |
| 10 | 2. Translate every complete pack. Do not satisfy parity by copying English. |
| 11 | 3. If an English value changes, update its translations as well. |
| 12 | |
| 13 | Keep `{named}` placeholders literal. Commands, key names, URLs, product terms, |
| 14 | and glyphs follow the conventions enforced by localization tests; ordinary |
| 15 | prose should be natural and compact. Preserve intentional edge whitespace. |
| 16 | |
| 17 | Localization migrations are one-way: new and touched surfaces use typed |
| 18 | `MessageId` keys and shared packs. Do not add renderer-local language branches |
| 19 | or preserve one because a snapshot expects the old shape. Prefer direct render |
| 20 | inspection for copy and layout; keep narrow parity/script checks only where they |
| 21 | cheaply prevent a real untranslated or malformed pack. |
| 22 | |
| 23 | Adding a locale also requires its `Locale` registry/display/parse entries, |
| 24 | onboarding picker entry, `UiLocale` schema value, and setup/config match arms. |
| 25 | The registry is the source of truth. Translated root READMEs are a separate |
| 26 | surface with `scripts/check-readme-translations.py` available as a focused |
| 27 | consistency check. |
| 28 |