---
name: i18n
description: Use when a code or template change introduces a new translation message key, in either the framework CLI (aegis/i18n/locales/) or a generated project's CLI (the app/i18n/locales/ template tree). Covers adding the real English string, stubbing the same key into every other locale for parity, and the separate translation PR that later replaces placeholders with reviewed native text.
---

# i18n

Adds a new i18n message key so `tests/core/test_i18n.py` (framework side) or
the generated project's own `tests/test_i18n.py` keeps passing. Both trees
share the same rule: a key that exists in English must exist, with some
value, in every other locale file, or the completeness test fails by name.

## When to use

Use when a feature or fix needs a brand-new string shown through the
translation layer (`t("some.key")` or `lazy_t("some.key")`), in either:

- The framework's own CLI (`aegis ...` commands), backed by
  `aegis/i18n/locales/`.
- A generated project's CLI (`app/i18n/locales/` under the copier template),
  which is a separate, parallel i18n tree with the same shape.

Do NOT use this skill to perform the actual translation work into
non-English languages; that is a separate, later PR (see Procedure below).
Do NOT use it for changing the wording of an existing English string without
adding a key; that is ordinary feature work, though it still needs the
placeholder value updated in every other locale if the value materially
changes (rare - most wording tweaks are English-only maintenance and do not
require this skill).

## Files that change

Framework i18n (`aegis/i18n/`):

- `aegis/i18n/locales/en.py`: canonical `MESSAGES: dict[str, str]`. Add the
  key with its real English value under the matching section-comment banner
  (e.g. `# --- Validation ---`, `# --- Interactive: AI service ---`). Keys are
  dot-separated `<area>.<name>`, matching existing groups such as
  `service.<name>`, `component.<name>`, `interactive.*`, `projectmap.*`,
  `add_service.*`, `deploy.*`.
- `aegis/i18n/locales/{de,es,fr,ja,ko,ru,zh,zh_hant}.py`: add the SAME key to
  each file, value = the English string, unmodified (a placeholder, not a
  translation).
- `aegis/i18n/locales/__init__.py`: `AVAILABLE_LOCALES` set; only touch this
  if adding a whole new locale, not a new key.
- `aegis/i18n/registry.py`: `translate()` does the lookup and fallback; no
  edit needed for a new key, it is generic over the dict.
- `tests/core/test_i18n.py`: `TestMessageCompleteness` is the gate. A missing
  key fails with a message like `Keys in en but not de: {'the.new.key'}`; an
  extra key (present in a locale but not English) fails the mirror-image
  assertion.

Generated-project i18n (a template change, see the template-dev skill for
the commit/render caveat):

- `aegis/templates/copier-aegis-project/{{ project_slug }}/app/i18n/locales/en.py`
- `aegis/templates/copier-aegis-project/{{ project_slug }}/app/i18n/locales/{de,es,fr,ja,ko,ru,zh,zh_hant}.py`
- `aegis/templates/copier-aegis-project/{{ project_slug }}/app/i18n/registry.py.jinja`:
  same fallback-chain `translate()`; no edit needed for a new key.
- `aegis/templates/copier-aegis-project/{{ project_slug }}/tests/test_i18n.py`:
  the generated project's own completeness test. It imports only `en` and
  `zh` explicitly and asserts those two key sets match; it does not loop over
  all nine locales the way the framework's test does. Stub the key into all
  eight non-English locales anyway, for consistency with the framework rule
  and to keep every locale file real (no dangling English-only keys).

## Procedure

Adding a new key:

1. Decide which tree owns the string (framework CLI vs generated-project
   CLI). If both need it independently, repeat the rest of these steps once
   per tree.
2. Write or adjust the consuming code to call `t("<area>.<name>", ...)` or
   `lazy_t("<area>.<name>", ...)` at the call site.
3. Add the key with its real English string to that tree's `en.py`, under
   the appropriate section-comment banner, following the existing
   `<area>.<name>` naming.
4. Add the same key to every other locale file in that tree, using the
   English string as the value (a placeholder, not a translation).
5. Run the gates (see Gates below) and confirm the completeness test passes.
6. If the generated-project tree changed, treat it as a template change:
   commit it (or use `aegis init --dev`) before validating with
   `make test-template`, per the template-dev skill.

Translation PR (separate flow, later):

1. Take the placeholder (English-value) entries in the non-English locale
   files and replace them with real, native translations.
2. The agent produces the initial translation pass.
3. A human translator reviews and corrects it; iterate back and forth until
   the wording reads native, not like a literal translation. Mandarin is the
   main quality bar for "does this sound native."
4. Keep phrasing compact: these are CLI strings rendered in a terminal.
   Prefer a compact, natural phrase over a longer one that is technically
   clearer; skip "clearer but longer" rewrites suggested along the way.
5. Run the same gates again; only wording changed, so the completeness test
   should already pass, but confirm no key was dropped in the edit.

## Gates

- `make check` (framework side: lint, typecheck, `tests/core/test_i18n.py`
  included in the default test run) must pass whenever
  `aegis/i18n/locales/` changed.
- `make test-template` when the generated-project locale files under
  `aegis/templates/copier-aegis-project/{{ project_slug }}/app/i18n/locales/`
  changed; this generates a project and runs its own test suite, including
  `tests/test_i18n.py`.

## Pitfalls

- Adding a key to `en.py` only fails `tests/core/test_i18n.py`, which checks
  both directions (missing keys and extra keys) for every locale, so the
  key must exist everywhere before `make check` is green.
- Do not write real translations in the same change that introduces the key;
  that is the separate translation PR's job, done with a human translator in
  the loop, not invented inline.
- Word-for-word translations read wrong to native speakers; the bar is
  natural, native phrasing, and Mandarin is where this has mattered most in
  review.
- CLI strings render in a fixed terminal width; prefer the compact phrasing
  and skip "clearer but longer" rewrites even when they read a bit better in
  isolation.
- Generated-project locale edits are template changes: Copier renders from
  the committed git state (or the working tree only under `aegis init
  --dev`), so an uncommitted edit under `app/i18n/locales/` will not show up
  in a freshly generated project until it is committed.
- The runtime fallback in `translate()` (current locale, then English, then
  the raw key) means a missing locale entry would still show something
  reasonable at runtime, but `tests/core/test_i18n.py` does not rely on
  runtime behavior; it asserts exact key-set equality, so relying on the
  fallback instead of stubbing the key still fails the gate.
- The generated project's own `tests/test_i18n.py` only compares `en` against
  `zh` by name; it will not catch a key missing from `de`, `es`, `fr`, `ja`,
  `ko`, `ru`, or `zh_hant`. Stub the key into all eight non-English locales
  regardless, since that test's narrower coverage is not a license to skip
  the others.