nextjs-i18n

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Next.js 16 Internationalization

Next.js 16 国际化

Complete i18n solution with next-intl or DIY dictionary approach.

使用next-intl或自定义字典方案的完整i18n解决方案。

Agent Workflow (MANDATORY)

Agent 工作流（强制要求）

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.

在进行任何实现之前，使用

TeamCreate

生成3个Agent：

fuse-ai-pilot:explore-codebase - 分析现有i18n配置和消息文件
fuse-ai-pilot:research-expert - 通过Context7/Exa验证最新的next-intl文档
mcp__context7__query-docs - 检查区域配置和模式

实现完成后，运行fuse-ai-pilot:sniper进行验证。

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

构建多语言Next.js 16应用
需要基于区域的路由，使用
```
[locale]
```
动态路由段
实现语言切换器和URL本地化
根据区域设置格式化日期、数字、货币和相对时间
使用hreflang标签和本地化元数据进行SEO优化
支持从右到左（RTL）的语言

Why next-intl

选择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

特性	优势
App Router原生支持	完整支持Server Components
类型安全的消息	TypeScript自动补全消息键
ICU消息格式	支持复数、性别、选择表达式
异步消息加载	按需加载对应区域的翻译内容
兼容proxy.ts	适配Next.js 16代理模式
丰富的格式化能力	日期、数字、列表、相对时间格式化

Two Approaches

两种实现方案

1. next-intl (Recommended)

1. next-intl（推荐）

Full-featured library with routing, formatting, and type safety. Best for production applications needing comprehensive i18n support.

功能完整的库，包含路由、格式化和类型安全。适合需要全面i18n支持的生产环境应用。

2. DIY Dictionary

2. 自定义字典方案

Lightweight approach using dynamic imports for simple translation needs. Good for projects wanting minimal dependencies.

轻量级方案，使用动态导入满足简单翻译需求。适合希望最小化依赖的项目。

SOLID Architecture

SOLID架构

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

所有i18n代码统一组织在

modules/cores/i18n/

目录下：

config/ - 路由配置、区域定义
interfaces/ - 消息和区域的TypeScript类型
services/ - 请求处理器、消息加载器
messages/ - 各区域对应的JSON翻译文件

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

src/modules/cores/i18n/src/config/routing.ts

- 区域路由配置

```
src/modules/cores/i18n/messages/en.json
```
- 英文翻译文件
```
src/modules/cores/i18n/messages/fr.json
```
- 法文翻译文件
```
proxy.ts
```
- 区域检测和重定向逻辑

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

所有路由都以

[locale]

动态路由段作为前缀：

```
/en/about
```
→ 英文关于页面
```
/fr/about
```
→ 法文关于页面
```
/
```
→ 重定向到默认区域

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

使用next-intl提供的本地化导航组件，自动处理区域相关逻辑：

Link - 支持区域的锚点链接
redirect - 服务端区域重定向
usePathname - 获取不含区域的当前路径
useRouter - 编程式导航

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

需求	参考文档
初始配置	installation.md, routing-setup.md
路由配置	routing-config.md, middleware-proxy.md
翻译实现	translations.md, messages-validation.md
格式化工具	formatting.md
组件开发	server-components.md, client-components.md
导航实现	navigation.md
TypeScript支持	typescript.md
SEO优化	seo.md
测试方案	testing.md
自定义方案	diy-dictionaries.md, diy-locale-detection.md

Message Formatting

消息格式化

ICU MessageFormat

ICU消息格式

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

复数处理 -

{count, plural, one {# item} other {# items}}

选择表达式 -

{gender, select, male {He} female {She} other {They}}

富文本 - 支持消息中的粗体、斜体、链接

Formatters

格式化工具

formatDate - Locale-aware date formatting
formatNumber - Currency, percentages, decimals
formatList - Conjunction/disjunction lists
formatRelativeTime - "2 hours ago", "in 3 days"

formatDate - 基于区域的日期格式化
formatNumber - 货币、百分比、小数格式化
formatList - 连接/分离列表格式化
formatRelativeTime - 格式化如"2小时前"、"3天后"的相对时间

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

类型安全的消息键 - 使用TypeScript实现消息键自动补全
消息命名空间 - 按功能/页面组织消息，提升可维护性
优先服务端加载 - 在服务端加载翻译内容，避免增加客户端包体积
SEO hreflang标签 - 为所有区域添加替代链接
RTL语言支持 - 使用
```
dir
```
属性适配从右到左的语言
** fallback区域设置** - 配置默认区域，处理缺失的翻译内容

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.

本地化的错误和加载状态需要特殊处理：

```
[locale]/error.tsx
```
- 本地化错误边界
```
[locale]/not-found.tsx
```
- 本地化404页面
```
global-error.tsx
```
- 根错误回退组件

完整模式请参考error-files.md。