localization
Best practices for i18n / localization in web apps (i18next / react-i18next and similar). Auto-activates when adding or editing user-facing text, translation keys, locale files, language switching/rou
SKILL.mdskills/03-product-engineering/localization/SKILL.md
GitHubLocalization (i18n)
Goal: every user-facing string is translatable, present in all locales, and rendered through the i18n layer — never hardcoded. Keep keys stable and semantic; keep locale files in sync.
Core principles
- No hardcoded user-facing strings. Route every label/message through the translate function (
t('...')/<Trans>). This includes placeholders, aria-labels, toasts, validation messages, empty/error states. - One source of truth for languages. Keep the supported-language list and the default/fallback in a single config module (e.g.
i18n.ts) and import it — don't re-list languages ad hoc. A helper to validate a language code (isLangType) avoids bad values. - Keys live in all locales. When you add a key, add it to every locale file. A missing key silently falls back to the default language — easy to ship a gap. Keep file shapes identical across locales.
- Stable, semantic keys. Use dot-path nesting grouped by screen/feature (
cargoList.searchPlaceholder) plus a shared bucket for reusable strings (common.save). camelCase keys; reserve UPPER_SNAKE_CASE for enum-value keys. - Interpolation, not concatenation. Use
{{var}}placeholders (t('items.count', { count })) instead of string concatenation, so word order can vary per language.
Setup (i18next example)
i18n.use(httpBackend).use(initReactI18next).init({
supportedLngs: langCodes,
fallbackLng: DEFAULT_LANG,
lng: savedLanguage, // from storage, validated
interpolation: { escapeValue: false }, // the view layer already escapes
backend: { loadPath: '/locales/{{lng}}.json' },
})
- Lazy-load locales over HTTP (
i18next-http-backend) so the bundle isn't bloated by every language. - Persist the chosen language (e.g.
localStorage), validate it on read, fall back to default. - Decide up front: namespaces (split large apps into multiple files per language) vs a single flat file with dot-path nesting. Be consistent.
Consuming translations
const { t, i18n } = useTranslation()
<input placeholder={t('search.placeholder')} />
<span>{t('items.count', { count })}</span>
t('actions.reset', { defaultValue: 'Reset' }) // inline fallback for safety
- For rich text with embedded markup, use
<Trans i18nKey="...">. - Pluralization: prefer i18next's plural suffixes (
key_one/key_other) over hand-rolled singular/plural keys, when the i18n lib supports it.
Translating backend enums / dynamic labels (central helper pattern)
Never render raw enum strings from the API. Write one helper per enum domain that normalizes the raw value and looks up a key, with a graceful default:
export function enumLabel(t: TFunction, raw: string): string {
const key = raw.trim().toUpperCase().replace(/[\s-]+/g, '_')
if (!key) return '—'
return t(`<enumGroup>.${key}`, { defaultValue: raw.replace(/_/g, ' ') })
}
- Add each enum value as a key under its group in all locale files; the helper picks them up automatically.
- For values the backend itself localizes (it returns
{ names: { en, ru, … } }orname_en/name_ru), select by current language with a fallback chain (current → default → first available) instead of a locale-file key.
Language switching & routing
- If language is in the URL (e.g.
/:lang/...), a provider should read the segment, validate it, callchangeLanguage, persist it, and redirect bare/invalid paths to a valid prefix. Build links through typed path helpers (see [[routing-pages]]), never hardcode the prefix. - Send the active language to the backend via a request header (e.g.
Accept-Language/ a customX-Language) — see [[api-communication]]. If some languages aren't supported server-side yet, map them to a supported one for the header while still localizing fully on the client.
Number / date / currency formatting
Use the platform Intl APIs (Intl.NumberFormat, Intl.DateTimeFormat) or a date lib's locale support — not translation keys. Map your app language codes to BCP-47 locales (e.g. en → en-US). Special-case currencies/units that need bespoke symbols or rounding.
Don'ts
- Don't hardcode strings or render raw enum values in the UI.
- Don't add a key to only some locale files (creates silent fallback gaps).
- Don't build sentences by concatenation — use interpolation.
- Don't scatter the supported-language list — import it from one config.
- Don't hardcode language/route prefixes — use typed path helpers.