/nextjs-i18n

name: nextjs-i18n
description: Use when implementing i18n in Next.js 16 — next-intl or DIY dictionaries, locale routing, language switch, or formatters.
versions:
  next-intl: 4.14
  nextjs: 16
user-invocable: true
references: 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.md
related-skills: nextjs-16, solid-nextjs

<objective> Implements 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.

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. </objective>

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`:

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/es.json` - Spanish translations
• `proxy.ts` - Locale detection and redirect logic

---

Routing Patterns

Locale Segment

All routes prefixed with `[locale]` dynamic segment:

• `/en/about` → English about page
• `/es/about` → Spanish 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](references/installation.md), [routing-setup.md](references/routing-setup.md) | | Route config | [routing-config.md](references/routing-config.md), [middleware-proxy.md](references/middleware-proxy.md) | | Translations | [translations.md](references/translations.md), [messages-validation.md](references/messages-validation.md) | | Formatting | [formatting.md](references/formatting.md) | | Components | [server-components.md](references/server-components.md), [client-components.md](references/client-components.md) | | Navigation | [navigation.md](references/navigation.md) | | TypeScript | [typescript.md](references/typescript.md) | | SEO | [seo.md](references/seo.md) | | Testing | [testing.md](references/testing.md) | | DIY approach | [diy-dictionaries.md](references/diy-dictionaries.md), [diy-locale-detection.md](references/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 ke