✓ Recommended
i18n / Internationalization Patterns
Internationalization with react-intl, next-intl, i18next, and ICU message format.
CLAUDE.md
# i18n / Internationalization Patterns
You are an expert in internationalization (i18n), localization (l10n), and multilingual web applications.
Translation Architecture:
- Store translations in JSON files per locale: `en.json`, `de.json`, `ja.json`
- Use nested keys for organization: `{ "auth": { "login": "Sign in", "logout": "Sign out" } }`
- Never hardcode user-facing strings — always use translation keys
- Extract strings with tooling: `formatjs extract` or `i18next-parser`
- Use ICU MessageFormat for plurals, gender, and complex formatting
React Libraries:
- react-intl (FormatJS): `<FormattedMessage id="greeting" values={{ name }} />` or `intl.formatMessage()`
- next-intl: built for Next.js App Router — `useTranslations('namespace')`, server component support
- i18next + react-i18next: `const { t } = useTranslation(); t('key')` — most popular, plugin ecosystem
- Wrap app in provider with current locale and messages
Pluralization & ICU:
- ICU format: `"items": "{count, plural, =0 {No items} one {1 item} other {{count} items}}"`
- Gender: `"{gender, select, male {He} female {She} other {They}} liked your post"`
- Select: `"{type, select, dog {Dog} cat {Cat} other {Animal}}"`
- Number formatting: `intl.formatNumber(1234.5, { style: 'currency', currency: 'EUR' })`
- Date formatting: `intl.formatDate(date, { dateStyle: 'long' })` — never use manual date formatting
URL Strategy:
- Path prefix: `/en/about`, `/de/about` — best for SEO, clear locale signal
- Subdomain: `en.example.com` — good for separate deployments per locale
- Set `<html lang="en">` and `<link rel="alternate" hreflang="de" href="...">`
- Use middleware to detect locale from Accept-Language header, cookie, or URL
Right-to-Left (RTL):
- Set `dir="rtl"` on html element for Arabic, Hebrew, Farsi, Urdu
- Use CSS logical properties: `margin-inline-start` not `margin-left`
- Tailwind: use `rtl:` variant — `rtl:text-right rtl:mr-0 rtl:ml-4`
- Test with `dir="rtl"` during development — layout bugs are common
Best Practices:
- Never concatenate strings for translation — use interpolation: `t('greeting', { name })`
- Avoid splitting sentences across multiple keys — translators need full context
- Use namespaces to organize large apps: `common`, `auth`, `dashboard`
- Provide context comments for translators: `"save_button": "Save" // Button in settings form`
- Lazy-load locale data: only download the current locale's translations
- Test with pseudolocalization to catch hardcoded strings and layout overflow
Add to your project root CLAUDE.md file, or append to an existing one.