Next.js 16 Internationalization
Complete i18n solution with next-intl or DIY dictionary approach.
Agent Workflow (MANDATORY)
Before ANY implementation, launch in parallel:
- 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-i18n3description: Next.js 16 internationalization with next-intl or DIY. Use when implementing i18n, translations, localization, multilingual, language switch, locale routing, or formatters.4---5
6# Next.js 16 Internationalization
7
8Complete i18n solution with next-intl or DIY dictionary approach.
9
10## Agent Workflow (MANDATORY)
11
12Before ANY implementation, launch in parallel:
13
141. **fuse-ai-pilot:explore-codebase** - Analyze existing i18n setup and message files
152. **fuse-ai-pilot:research-expert** - Verify latest next-intl docs via Context7/Exa
163. **mcp__context7__query-docs** - Check locale config and patterns
17
18After implementation, run **fuse-ai-pilot:sniper** for validation.
19
20---
21
22## Overview
23
24### When to Use
25
26- Building multilingual Next.js 16 applications
27- Need locale-based routing with `[locale]` dynamic segment
28- Implementing language switcher and URL localization
29- Formatting dates, numbers, currencies, and relative times per locale
30- SEO optimization with hreflang tags and localized metadata
31- Supporting right-to-left (RTL) languages
32
33### Why next-intl
34
35| 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 |
43
44---
45
46## Two Approaches
47
48### 1. next-intl (Recommended)
49
50Full-featured library with routing, formatting, and type safety. Best for production applications needing comprehensive i18n support.
51
52### 2. DIY Dictionary
53
54Lightweight approach using dynamic imports for simple translation needs. Good for projects wanting minimal dependencies.
55
56---
57
58## SOLID Architecture
59
60### Module Structure
61
62All i18n code organized in `modules/cores/i18n/`:
63
64- **config/** - Routing configuration, locale definitions
65- **interfaces/** - TypeScript types for messages and locales
66- **services/** - Request handlers, message loaders
67- **messages/** - JSON translation files per locale
68
69### File Locations
70
71- `src/modules/cores/i18n/src/config/routing.ts` - Locale routing config
72- `src/modules/cores/i18n/messages/en.json` - English translations
73- `src/modules/cores/i18n/messages/fr.json` - French translations
74- `proxy.ts` - Locale detection and redirect logic
75
76---
77
78## Routing Patterns
79
80### Locale Segment
81
82All routes prefixed with `[locale]` dynamic segment:
83
84- `/en/about` → English about page
85- `/fr/about` → French about page
86- `/` → Redirects to default locale
87
88### Navigation Components
89
90Use localized navigation from next-intl for automatic locale handling:
91
92- **Link** - Locale-aware anchor links
93- **redirect** - Server-side locale redirect
94- **usePathname** - Current path without locale
95- **useRouter** - Programmatic navigation
96
97---
98
99## Reference Guide
100
101| 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) |
113
114---
115
116## Message Formatting
117
118### ICU MessageFormat
119
120- **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 messages
123
124### Formatters
125
126- **formatDate** - Locale-aware date formatting
127- **formatNumber** - Currency, percentages, decimals
128- **formatList** - Conjunction/disjunction lists
129- **formatRelativeTime** - "2 hours ago", "in 3 days"
130
131---
132
133## Best Practices
134
1351. **Type-safe keys** - Use TypeScript for message key autocompletion
1362. **Namespace messages** - Organize by feature/page for maintainability
1373. **Server-first** - Load translations on server, avoid client bundles
1384. **SEO hreflang** - Add alternate links for all locales
1395. **RTL support** - Use `dir` attribute for right-to-left languages
1406. **Fallback locale** - Configure default for missing translations
141
142---
143
144## Error Handling
145
146### Special Files
147
148Localized error and loading states require specific handling:
149
150- `[locale]/error.tsx` - Localized error boundary
151- `[locale]/not-found.tsx` - Localized 404 page
152- `global-error.tsx` - Root error fallback
153
154See [error-files.md](references/error-files.md) for complete patterns.
majiayu000