Localization (i18n)
Multi-language text via i18next, with device-locale detection and a typed translation key.
The rule
This is the whole text, exactly as your agent receives it. Nothing is held back for the paid tier.
- User-facing text goes through
t('namespace.key')— never a hardcoded English string in a component. A hardcoded string is invisible to every locale except the one the author was looking at. - Interpolation uses single braces —
{name},{count}— instead of i18next's normal default, because this project's own generator claims the double-brace delimiter for its own templates at generation time. The locale JSON files and thei18next.init()config insrc/i18n/index.tswere changed together to avoid the collision. Do not "fix" one without the other — reverting the interpolation delimiter without also reverting every locale file breaks every interpolated string at once, silently (i18next just stops substituting). - Add a key to every locale file at the same time —
en.jsonandes.jsonare meant to stay in lockstep. A key present only inen.jsonsilently falls back to English for every other locale (correct behavior, but worth noticing rather than assuming was intentional). - Plural keys follow i18next's
_one/_othersuffix convention (items_one,items_other) —t('items', { count })picks the right one automatically. Do not hand-roll a plural check with a ternary.
6 formats, one per tool
Each tab is the file that tool actually reads, at the path it actually looks in. Knowing where each one looks is most of the work of supporting it.
---
description: Localization (i18n) conventions
globs: ["src/i18n/**/*.ts", "src/i18n/**/*.tsx", "src/i18n/locales/**/*.json"]
alwaysApply: false
---
# Localization (i18n)
- User-facing text goes through `t('namespace.key')` — never a hardcoded
English string in a component. A hardcoded string is invisible to every
locale except the one the author was looking at.
- Interpolation uses single braces — `{name}`, `{count}` — instead of
i18next's normal default, because this project's own generator claims the
double-brace delimiter for its own templates at generation time. The
locale JSON files and the `i18next.init()` config in `src/i18n/index.ts`
were changed together to avoid the collision. Do not "fix" one without the
other — reverting the interpolation delimiter without also reverting every
locale file breaks every interpolated string at once, silently (i18next
just stops substituting).
- Add a key to **every** locale file at the same time — `en.json` and
`es.json` are meant to stay in lockstep. A key present only in `en.json`
silently falls back to English for every other locale (correct behavior,
but worth noticing rather than assuming was intentional).
- Plural keys follow i18next's `_one`/`_other` suffix convention
(`items_one`, `items_other`) — `t('items', { count })` picks the right one
automatically. Do not hand-roll a plural check with a ternary.
Hand-written by the module author, frontmatter and all. It is the source the four derived formats are rendered from, so a correction lands here first.
What else this module writes
The rule is one file of several. Selecting Localization (i18n) contributes all of this too — merged with every other module you pick, with conflicts resolved rather than duplicated.
Advisory history
Every time this rule turned out to be wrong, and what we did about it.
This rule has been accurate since it was published. That is a fact about the rule, not a promise about the future — which is the whole reason this section exists.
Pro tells you the day a correction lands that affects a repo you actually have.
See what Pro adds →The wizard picks the rest of the stack with you, writes all 6 formats, and leaves a manifest so check can tell you when any of it drifts.