| name | i18n-web-guide |
| description | I18n for JS/React/Next.js — routing, SEO, ICU messages, Intl formatting, RTL/LTR, Arabic support. Trigger for: multilingual apps, hreflang, locale URLs, date/number/currency, RTL styling, Tailwind logical props, next-intl/lingui/react-i18next, translation files, Arabic/cursive bugs, dir attribute, writing modes. Claude Code: trigger when working on JS/React/Next.js codebase with any i18n task.
|
I18n Web Apps
Stack: JS · React · Next.js · Vite · Remix · Astro
Reference files (read relevant one per task):
- Routing →
references/01-routing.md
- SEO →
references/02-seo.md
- Messages/ICU →
references/03-messages.md
- Data formatting →
references/04-data-formatting.md
- Tools/libraries →
references/05-tools.md
- UI/direction/CSS →
references/06-ui.md
- Framework code →
references/07-framework-patterns.md
- Sources/links →
references/00-master-references.md (only when user asks)
Claude Code
Check package.json + existing /messages, /locales, /i18n before acting. Write real files, inspect before fixing bugs, match project conventions.
Setup Order
- URL routing — Next.js: middleware +
[locale]; React: locale wrapper route
- i18n library — Next.js:
next-intl; React: react-i18next or lingui
- Message files —
/messages/en.json source of truth; all locales mirror structure
- Direction —
dir + lang on <html> from active locale
- Format utils —
lib/format.ts wrapping Intl.*
- Apply to shared components — never hard-code user-visible strings
Stack
| Stack | Library | Routing |
|---|
| Next.js App Router | next-intl or lingui | app/[locale]/ + middleware |
| Next.js Pages Router | next-intl / next-i18next | pages/[locale]/ |
| React Vite/CRA | react-i18next / lingui | React Router v6 wrapper |
| Remix | remix-i18next | Loader detection |
| Astro | astro-i18n / i18next | src/pages/[locale]/ |
Rules
- All text in JSON/YAML — never hard-code strings
- ICU format —
{name}, {n, plural, ...}, {g, select, ...}
- Validate — TypeScript types or
i18n-check CLI
- Logical CSS —
margin-inline-start not margin-left; Tailwind: ps-*/pe-*
- No
letter-spacing on Arabic/Persian — breaks letterforms
- Human review required — machine translation not production-ready
Intl.* for all formatting — never manual functionsdir="auto" on content blocks for mixed-direction UGC- One hreflang method — sitemap OR
<link> OR HTTP headers
- Next.js: locale via
middleware.ts → layout, never read from URL in components
