Next.js i18n 设置 (nextjs-i18n-setup)

Next.js i18n 设置 (nextjs-i18n-setup) 是做什么的？

在现有的 Next.js App Router 项目中引导并搭建 next-intl，使用现代的 next/root-params、动态段 app/[locale]/，并区分 Next.js 16+（使用 proxy.ts） 与 Next.js <=15（使用 middleware.ts）。

[!TIP] 模板与样板代码： 查阅 references/templates.md 获取可用的完整代码模板。 快速执行： 将验证任务委托给轻量级子代理（Model: 'flash'）。

---

1. 架构规则与要求

1. 元数据约定： 确保 docs/project.json 包含以下内容：

   "dictionaries_dir": "messages",
   "dictionary_file_pattern": "[locale].json"
   

2. Next.js 版本拦截：
   • Next.js 16+：使用 proxy.ts（或 src/proxy.ts）。迁移并移除任何旧的 middleware.ts。
   • Next.js <=15：使用 middleware.ts（或 src/middleware.ts）。
3. 现代根参数： 在 i18n/request.ts 中使用 next/root-params（await rootParams.locale()）。禁止使用已废弃的 requestLocale 和 setRequestLocale()。
4. 导航： 从 i18n/navigation.ts 导出 Link、redirect、usePathname、useRouter（纯 TypeScript，不含 JSX）。
5. 静态生成： 根布局 app/[locale]/layout.tsx 必须导出 generateStaticParams()，为所有支持的语言返回 { locale }。

---

2. 设置清单

• 第 0 步：审计：检查 docs/project.json（supported_languages）和 package.json 中的 Next.js 版本。
• 第 1 步：安装：运行 <pkg_mgr> add next-intl（例如 pnpm add next-intl）。
• 第 2 步：配置元数据：确保 docs/project.json 中包含 dictionaries_dir: "messages"。
• 第 3 步：路由：使用 defineRouting 创建 i18n/routing.ts（参见模板）。
• 第 4 步：请求处理器：使用 next/root-params 创建 i18n/request.ts（参见模板）。
• 第 5 步：导航辅助：创建 i18n/navigation.ts（参见模板）。
• 第 6 步：Next.js 插件：使用 createNextIntlPlugin() 包装 next.config.ts（参见模板）。
• 第 7 步：拦截器：创建 proxy.ts（Next 16+）或 middleware.ts（Next <=15），并包含资源过滤匹配器（参见模板）。
• 第 8 步：起始字典：确保所有支持的语言都存在 messages/[locale].json，且具有匹配的基础键。
• 第 9 步：迁移布局和路由：将顶级路由移动到 app/[locale]/ 下。配置动态 dir、lang、generateStaticParams 和 <NextIntlClientProvider>（参见模板）。
• 第 10 步：类型增强：在 global.d.ts 中声明 AppConfig.Messages（参见模板）。
• 第 11 步：导航导入：更新现有组件中的所有内部链接，使用 @/i18n/navigation。
• 第 12 步：验证：运行验证脚本并构建：

  pwsh .agents/skills/nextjs-i18n-setup/scripts/verify-setup.ps1 -Quiet
  pnpm run build
  

---

3. 设置执行报告模板

## 🌐 Next.js i18n 设置执行报告

| 步骤 / 组件         | 目标文件                       | 状态                            | 备注                    |
| :----------------- | :--------------------------- | :------------------------------ | :----------------------- |
| **包**             | `package.json` (`next-intl`) | `[已实现]` / `[未触及]`          | 已安装运行时              |
| **项目配置**       | `docs/project.json`          | `[已实现]` / `[未触及]`          | 配置了消息目录            |
| **路由**           | `i18n/routing.ts`            | `[已实现]` / `[未触及]`          | 区域设置与默认值          |
| **请求**           | `i18n/request.ts`            | `[已实现]` / `[未触及]`          | next/root-params         |
| **导航**           | `i18n/navigation.ts`         | `[已实现]` / `[未触及]`          | 纯 TS 辅助函数            |
| **插件**           | `next.config.ts`             | `[已实现]` / `[未触及]`          | 已包装 withNextIntl       |
| **拦截器**         | `proxy.ts` / `middleware.ts` | `[已实现]` / `[未触及]`          | 路由匹配器                |
| **字典**           | `messages/[locale].json`     | `[已实现]` / `[未触及]`          | 起始字典                  |
| **布局**           | `app/[locale]/layout.tsx`    | `[已实现]` / `[未触及]`          | 静态参数与 Provider       |
| **类型**           | `global.d.ts`                | `[已实现]` / `[未触及]`          | AppConfig 增强            |
| **验证**           | `verify-setup.ps1` 与构建    | `[通过]`                          | 干净构建                  |