Covers [locale]-prefixed routing, localized navigation components (Link, redirect, usePathname, useRouter), date/number/currency/relative-time formatting, RTL language support, SEO hreflang tags, and localized special files ([locale]/error.tsx, [locale]/not-found.tsx, global-error.tsx). This is the Next.js-specific i18n skill (App Router routing, proxy.ts integration) — for plain React apps without Next.js see react-i18n, and for Astro see astro-i18n.
Next.js 16 Internationalization
Complete i18n solution with next-intl or DIY dictionary approach.
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- 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 config
src/modules/cores/i18n/messages/en.json - English translations
src/modules/cores/i18n/messages/fr.json - French translations
proxy.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 page
global-error.tsx - Root error fallback
See error-files.md for complete patterns.
1---2name: nextjs-i18n3description: Use when implementing i18n in Next.js 16 — next-intl or DIY dictionaries, locale routing, language switch, or formatters.4versions:5 next-intl: 4.06 nextjs: 167user-invocable: true8references: references/installation.md, references/pages-router.md, references/routing-setup.md, references/routing-config.md, references/translations.md, references/formatting.md, references/navigation.md, references/server-components.md, references/client-components.md, references/middleware-proxy.md, references/error-files.md, references/configuration.md, references/plugin.md, references/extraction.md, references/messages-validation.md, references/typescript.md, references/testing.md, references/integrations.md, references/seo.md, references/core-library.md, references/runtime-requirements.md, references/diy-dictionaries.md, references/diy-locale-detection.md9related-skills: nextjs-16, solid-nextjs10metadata:11 source: https://skillmd.com/skills/fusengine/nextjs-i18n12---1314<objective>15Implements internationalization for Next.js 16 App Router apps via two approaches: next-intl (recommended — full Server Components support, type-safe messages, ICU MessageFormat, async message loading, proxy.ts-compatible routing) or a lightweight DIY dictionary approach using dynamic imports.1617Covers `[locale]`-prefixed routing, localized navigation components (Link, redirect, usePathname, useRouter), date/number/currency/relative-time formatting, RTL language support, SEO hreflang tags, and localized special files (`[locale]/error.tsx`, `[locale]/not-found.tsx`, `global-error.tsx`). This is the Next.js-specific i18n skill (App Router routing, proxy.ts integration) — for plain React apps without Next.js see react-i18n, and for Astro see astro-i18n.18</objective>1920# Next.js 16 Internationalization2122Complete i18n solution with next-intl or DIY dictionary approach.2324## Agent Workflow (MANDATORY)2526Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:27281. **fuse-ai-pilot:explore-codebase** - Analyze existing i18n setup and message files292. **fuse-ai-pilot:research-expert** - Verify latest next-intl docs via Context7/Exa303. **mcp__context7__query-docs** - Check locale config and patterns3132After implementation, run **fuse-ai-pilot:sniper** for validation.3334---3536## Overview3738### When to Use3940- Building multilingual Next.js 16 applications41- Need locale-based routing with `[locale]` dynamic segment42- Implementing language switcher and URL localization43- Formatting dates, numbers, currencies, and relative times per locale44- SEO optimization with hreflang tags and localized metadata45- Supporting right-to-left (RTL) languages4647### Why next-intl4849| Feature | Benefit |50|---------|---------|51| App Router native | Full Server Components support |52| Type-safe messages | TypeScript autocompletion for keys |53| ICU MessageFormat | Pluralization, gender, select expressions |54| Async message loading | Load translations on-demand per locale |55| proxy.ts compatible | Works with Next.js 16 proxy pattern |56| Rich formatting | Dates, numbers, lists, relative time |5758---5960## Two Approaches6162### 1. next-intl (Recommended)6364Full-featured library with routing, formatting, and type safety. Best for production applications needing comprehensive i18n support.6566### 2. DIY Dictionary6768Lightweight approach using dynamic imports for simple translation needs. Good for projects wanting minimal dependencies.6970---7172## SOLID Architecture7374### Module Structure7576All i18n code organized in `modules/cores/i18n/`:7778- **config/** - Routing configuration, locale definitions79- **interfaces/** - TypeScript types for messages and locales80- **services/** - Request handlers, message loaders81- **messages/** - JSON translation files per locale8283### File Locations8485- `src/modules/cores/i18n/src/config/routing.ts` - Locale routing config86- `src/modules/cores/i18n/messages/en.json` - English translations87- `src/modules/cores/i18n/messages/fr.json` - French translations88- `proxy.ts` - Locale detection and redirect logic8990---9192## Routing Patterns9394### Locale Segment9596All routes prefixed with `[locale]` dynamic segment:9798- `/en/about` → English about page99- `/fr/about` → French about page100- `/` → Redirects to default locale101102### Navigation Components103104Use localized navigation from next-intl for automatic locale handling:105106- **Link** - Locale-aware anchor links107- **redirect** - Server-side locale redirect108- **usePathname** - Current path without locale109- **useRouter** - Programmatic navigation110111---112113## Reference Guide114115| Need | Reference |116|------|-----------|117| Initial setup | [installation.md](references/installation.md), [routing-setup.md](references/routing-setup.md) |118| Route config | [routing-config.md](references/routing-config.md), [middleware-proxy.md](references/middleware-proxy.md) |119| Translations | [translations.md](references/translations.md), [messages-validation.md](references/messages-validation.md) |120| Formatting | [formatting.md](references/formatting.md) |121| Components | [server-components.md](references/server-components.md), [client-components.md](references/client-components.md) |122| Navigation | [navigation.md](references/navigation.md) |123| TypeScript | [typescript.md](references/typescript.md) |124| SEO | [seo.md](references/seo.md) |125| Testing | [testing.md](references/testing.md) |126| DIY approach | [diy-dictionaries.md](references/diy-dictionaries.md), [diy-locale-detection.md](references/diy-locale-detection.md) |127128---129130## Message Formatting131132### ICU MessageFormat133134- **Pluralization** - `{count, plural, one {# item} other {# items}}`135- **Select** - `{gender, select, male {He} female {She} other {They}}`136- **Rich text** - Support for bold, italic, links in messages137138### Formatters139140- **formatDate** - Locale-aware date formatting141- **formatNumber** - Currency, percentages, decimals142- **formatList** - Conjunction/disjunction lists143- **formatRelativeTime** - "2 hours ago", "in 3 days"144145---146147## Best Practices1481491. **Type-safe keys** - Use TypeScript for message key autocompletion1502. **Namespace messages** - Organize by feature/page for maintainability1513. **Server-first** - Load translations on server, avoid client bundles1524. **SEO hreflang** - Add alternate links for all locales1535. **RTL support** - Use `dir` attribute for right-to-left languages1546. **Fallback locale** - Configure default for missing translations155156---157158## Error Handling159160### Special Files161162Localized error and loading states require specific handling:163164- `[locale]/error.tsx` - Localized error boundary165- `[locale]/not-found.tsx` - Localized 404 page166- `global-error.tsx` - Root error fallback167168See [error-files.md](references/error-files.md) for complete patterns.