Next.js 16 Internationalization
Complete i18n solution with next-intl or DIY dictionary approach.
Agent Workflow (MANDATORY)
Before ANY implementation, use TeamCreate to spawn 3 agents:
- fuse-ai-pilot:explore-codebase - Analyze existing i18n setup and message files
- fuse-ai-pilot:research-expert - Verify latest next-intl docs via Context7/Exa
- mcp__context7__query-docs - Check locale config and patterns
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
When to Use
- Building multilingual Next.js 16 applications
- Need locale-based routing with
[locale] dynamic segment
- Implementing language switcher and URL localization
- Formatting dates, numbers, currencies, and relative times per locale
- SEO optimization with hreflang tags and localized metadata
- Supporting right-to-left (RTL) languages
Why next-intl
| Feature |
Benefit |
| App Router native |
Full Server Components support |
| Type-safe messages |
TypeScript autocompletion for keys |
| ICU MessageFormat |
Pluralization, gender, select expressions |
| Async message loading |
Load translations on-demand per locale |
| proxy.ts compatible |
Works with Next.js 16 proxy pattern |
| Rich formatting |
Dates, numbers, lists, relative time |
Two Approaches
1. next-intl (Recommended)
Full-featured library with routing, formatting, and type safety. Best for production applications needing comprehensive i18n support.
2. DIY Dictionary
Lightweight approach using dynamic imports for simple translation needs. Good for projects wanting minimal dependencies.
SOLID Architecture
Module Structure
All i18n code organized in modules/cores/i18n/:
- config/ - Routing configuration, locale definitions
- interfaces/ - TypeScript types for messages and locales
- services/ - Request handlers, message loaders
- messages/ - JSON translation files per locale
File Locations
src/modules/cores/i18n/src/config/routing.ts - Locale routing configsrc/modules/cores/i18n/messages/en.json - English translationssrc/modules/cores/i18n/messages/fr.json - French translationsproxy.ts - Locale detection and redirect logic
Routing Patterns
Locale Segment
All routes prefixed with [locale] dynamic segment:
/en/about → English about page/fr/about → French about page/ → Redirects to default locale
Navigation Components
Use localized navigation from next-intl for automatic locale handling:
- Link - Locale-aware anchor links
- redirect - Server-side locale redirect
- usePathname - Current path without locale
- useRouter - Programmatic navigation
Reference Guide
| Need |
Reference |
| Initial setup |
installation.md, routing-setup.md |
| Route config |
routing-config.md, middleware-proxy.md |
| Translations |
translations.md, messages-validation.md |
| Formatting |
formatting.md |
| Components |
server-components.md, client-components.md |
| Navigation |
navigation.md |
| TypeScript |
typescript.md |
| SEO |
seo.md |
| Testing |
testing.md |
| DIY approach |
diy-dictionaries.md, diy-locale-detection.md |
Message Formatting
ICU MessageFormat
- Pluralization -
{count, plural, one {# item} other {# items}}
- Select -
{gender, select, male {He} female {She} other {They}}
- Rich text - Support for bold, italic, links in messages
Formatters
- formatDate - Locale-aware date formatting
- formatNumber - Currency, percentages, decimals
- formatList - Conjunction/disjunction lists
- formatRelativeTime - "2 hours ago", "in 3 days"
Best Practices
- Type-safe keys - Use TypeScript for message key autocompletion
- Namespace messages - Organize by feature/page for maintainability
- Server-first - Load translations on server, avoid client bundles
- SEO hreflang - Add alternate links for all locales
- RTL support - Use
dir attribute for right-to-left languages
- Fallback locale - Configure default for missing translations
Error Handling
Special Files
Localized error and loading states require specific handling:
[locale]/error.tsx - Localized error boundary[locale]/not-found.tsx - Localized 404 pageglobal-error.tsx - Root error fallback
See error-files.md for complete patterns.
1---2name: nextjs-i18n-23description: Next.js 16 internationalization with next-intl or DIY. Use when implementing i18n, translations, localization, multilingual, language switch, locale routing, or formatters.4---56# Next.js 16 Internationalization78Complete i18n solution with next-intl or DIY dictionary approach.910## Agent Workflow (MANDATORY)1112Before ANY implementation, use `TeamCreate` to spawn 3 agents:13141. **fuse-ai-pilot:explore-codebase** - Analyze existing i18n setup and message files152. **fuse-ai-pilot:research-expert** - Verify latest next-intl docs via Context7/Exa163. **mcp__context7__query-docs** - Check locale config and patterns1718After implementation, run **fuse-ai-pilot:sniper** for validation.1920---2122## Overview2324### When to Use2526- Building multilingual Next.js 16 applications27- Need locale-based routing with `[locale]` dynamic segment28- Implementing language switcher and URL localization29- Formatting dates, numbers, currencies, and relative times per locale30- SEO optimization with hreflang tags and localized metadata31- Supporting right-to-left (RTL) languages3233### Why next-intl3435| Feature | Benefit |36|---------|---------|37| App Router native | Full Server Components support |38| Type-safe messages | TypeScript autocompletion for keys |39| ICU MessageFormat | Pluralization, gender, select expressions |40| Async message loading | Load translations on-demand per locale |41| proxy.ts compatible | Works with Next.js 16 proxy pattern |42| Rich formatting | Dates, numbers, lists, relative time |4344---4546## Two Approaches4748### 1. next-intl (Recommended)4950Full-featured library with routing, formatting, and type safety. Best for production applications needing comprehensive i18n support.5152### 2. DIY Dictionary5354Lightweight approach using dynamic imports for simple translation needs. Good for projects wanting minimal dependencies.5556---5758## SOLID Architecture5960### Module Structure6162All i18n code organized in `modules/cores/i18n/`:6364- **config/** - Routing configuration, locale definitions65- **interfaces/** - TypeScript types for messages and locales66- **services/** - Request handlers, message loaders67- **messages/** - JSON translation files per locale6869### File Locations7071- `src/modules/cores/i18n/src/config/routing.ts` - Locale routing config72- `src/modules/cores/i18n/messages/en.json` - English translations73- `src/modules/cores/i18n/messages/fr.json` - French translations74- `proxy.ts` - Locale detection and redirect logic7576---7778## Routing Patterns7980### Locale Segment8182All routes prefixed with `[locale]` dynamic segment:8384- `/en/about` → English about page85- `/fr/about` → French about page86- `/` → Redirects to default locale8788### Navigation Components8990Use localized navigation from next-intl for automatic locale handling:9192- **Link** - Locale-aware anchor links93- **redirect** - Server-side locale redirect94- **usePathname** - Current path without locale95- **useRouter** - Programmatic navigation9697---9899## Reference Guide100101| Need | Reference |102|------|-----------|103| Initial setup | [installation.md](references/installation.md), [routing-setup.md](references/routing-setup.md) |104| Route config | [routing-config.md](references/routing-config.md), [middleware-proxy.md](references/middleware-proxy.md) |105| Translations | [translations.md](references/translations.md), [messages-validation.md](references/messages-validation.md) |106| Formatting | [formatting.md](references/formatting.md) |107| Components | [server-components.md](references/server-components.md), [client-components.md](references/client-components.md) |108| Navigation | [navigation.md](references/navigation.md) |109| TypeScript | [typescript.md](references/typescript.md) |110| SEO | [seo.md](references/seo.md) |111| Testing | [testing.md](references/testing.md) |112| DIY approach | [diy-dictionaries.md](references/diy-dictionaries.md), [diy-locale-detection.md](references/diy-locale-detection.md) |113114---115116## Message Formatting117118### ICU MessageFormat119120- **Pluralization** - `{count, plural, one {# item} other {# items}}`121- **Select** - `{gender, select, male {He} female {She} other {They}}`122- **Rich text** - Support for bold, italic, links in messages123124### Formatters125126- **formatDate** - Locale-aware date formatting127- **formatNumber** - Currency, percentages, decimals128- **formatList** - Conjunction/disjunction lists129- **formatRelativeTime** - "2 hours ago", "in 3 days"130131---132133## Best Practices1341351. **Type-safe keys** - Use TypeScript for message key autocompletion1362. **Namespace messages** - Organize by feature/page for maintainability1373. **Server-first** - Load translations on server, avoid client bundles1384. **SEO hreflang** - Add alternate links for all locales1395. **RTL support** - Use `dir` attribute for right-to-left languages1406. **Fallback locale** - Configure default for missing translations141142---143144## Error Handling145146### Special Files147148Localized error and loading states require specific handling:149150- `[locale]/error.tsx` - Localized error boundary151- `[locale]/not-found.tsx` - Localized 404 page152- `global-error.tsx` - Root error fallback153154See [error-files.md](references/error-files.md) for complete patterns.
majiayu000