nextjs-i18n

通过两种方式为 Next.js 16 App Router 应用实现国际化：next-intl（推荐——全面支持 Server Components、类型安全的消息、ICU MessageFormat、异步消息加载，以及兼容 proxy.ts 的路由），或使用动态导入的轻量级 DIY 字典方案。

涵盖带 [locale] 前缀的路由、本地化导航组件（Link、redirect、usePathname、useRouter）、日期／数字／货币／相对时间格式化、RTL 语言支持、SEO hreflang 标签，以及本地化特殊文件（[locale]/error.tsx、[locale]/not-found.tsx、global-error.tsx）。这是针对 Next.js 的 i18n 技能（App Router 路由、proxy.ts 集成）——不使用 Next.js 的纯 React 应用请参阅 react-i18n，Astro 应用请参阅 astro-i18n。

Next.js 16 国际化

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

Agent 工作流（强制）

在进行任何实现之前，必须并行启动 3 个 Agent，每个调用一个 Agent，并指定 name：

1. fuse-ai-pilot:explore-codebase - 分析现有 i18n 配置和消息文件
2. fuse-ai-pilot:research-expert - 通过 Context7/Exa 核实最新的 next-intl 文档
3. mcp__context7__query-docs - 检查 locale 配置和模式

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

---

概述

适用场景

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

为什么选择 next-intl

功能	优势
原生支持 App Router	全面支持 Server Components
类型安全的消息	TypeScript 键名自动补全
ICU MessageFormat	复数、性别、select 表达式
异步消息加载	按需加载各 locale 的翻译
兼容 proxy.ts	适用于 Next.js 16 proxy 模式
丰富的格式化功能	日期、数字、列表、相对时间

---

两种方案

1. next-intl（推荐）

功能全面的库，提供路由、格式化和类型安全。最适合需要全面 i18n 支持的生产应用。

2. DIY 字典

使用动态导入的轻量级方案，适用于简单的翻译需求。适合希望尽量减少依赖项的项目。

---

SOLID 架构

模块结构

所有 i18n 代码均组织在 modules/cores/i18n/ 中：

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

文件位置

• src/modules/cores/i18n/src/config/routing.ts - locale 路由配置
• src/modules/cores/i18n/messages/en.json - 英文翻译
• src/modules/cores/i18n/messages/es.json - 西班牙语翻译
• proxy.ts - locale 检测和重定向逻辑

---

路由模式

Locale 段

所有路由均以 [locale] 动态段为前缀：

• /en/about → 英文关于页面
• /es/about → 西班牙语关于页面
• / → 重定向到默认 locale

导航组件

使用 next-intl 提供的本地化导航，自动处理 locale：

• Link - 自动适配 locale 的锚点链接
• redirect - 服务端 locale 重定向
• usePathname - 不含 locale 的当前路径
• useRouter - 编程式导航

---

参考指南

需求	参考资料
初始设置	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 方案	diy-dictionaries.md、diy-locale-detection.md

---

消息格式化

ICU MessageFormat

• 复数形式 - {count, plural, one {# item} other {# items}}
• 选择 - {gender, select, male {He} female {She} other {They}}
• 富文本 - 支持在消息中使用粗体、斜体和链接

格式化器

• formatDate - 根据区域设置格式化日期
• formatNumber - 货币、百分比和小数
• formatList - 并列或择一列表
• formatRelativeTime - “2 小时前”“3 天后”

---

最佳实践

1. 类型安全的键 - 使用 TypeScript 实现消息键自动补全
2. 消息命名空间 - 按功能或页面组织，便于维护
3. 服务端优先 - 在服务端加载翻译，避免打包到客户端
4. SEO hreflang - 为所有区域设置添加备用链接
5. 支持 RTL - 使用 dir 属性支持从右向左的语言
6. 回退区域设置 - 为缺失的翻译配置默认区域设置

---

错误处理

特殊文件

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

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

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