nextjs-i18n

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:

1. fuse-ai-pilot:explore-codebase - Analyze existing i18n setup and message files
2. fuse-ai-pilot:research-expert - Verify latest next-intl docs via Context7/Exa
3. 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

1. Type-safe keys - Use TypeScript for message key autocompletion
2. Namespace messages - Organize by feature/page for maintainability
3. Server-first - Load translations on server, avoid client bundles
4. SEO hreflang - Add alternate links for all locales
5. RTL support - Use dir attribute for right-to-left languages
6. 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.