next-intl-app-router

用途

本技能用于在 Next.js App Router 项目中配置并使用 next-intl，实现基于前缀的语言路由，例如 /en/about、/ja/about。当需要新增或调整国际化（i18n）、语言路由、翻译相关功能时适用。文档中的示例代码以可直接复制的独立文件形式存放在本技能的 examples/ 文件夹中，examples/README.md 说明了每个文件在项目中的放置位置。

文件结构

文档要求保持如下结构：

├── messages/
│   ├── en.json
│   ├── ja.json
│   └── ...
├── next.config.ts
└── src/
    ├── i18n/
    │   ├── request.ts
    │   ├── routing.ts
    │   └── navigation.ts
    ├── proxy.ts          # Next.js 16+（原 middleware.ts）
    └── app/
        ├── layout.tsx    # 根布局，此处不使用 NextIntlClientProvider
        └── [locale]/
            ├── layout.tsx
            ├── page.tsx
            └── ...

根布局不包裹 NextIntlClientProvider，只有 app/[locale]/layout.tsx 才包裹。

主要配置步骤

Next 配置：使用 createNextIntlPlugin() 包裹配置，默认路径为 ./i18n/request.ts，也可通过 createNextIntlPlugin('./src/i18n/request.ts') 指定自定义路径。
路由配置：在 src/i18n/routing.ts 中通过 defineRouting 集中定义 locales（示例为 en、ja、zh-CN、zh-TW）与 defaultLocale。
请求配置：src/i18n/request.ts 使用 getRequestConfig，从 [locale] 片段解析语言，并用 hasLocale 校验，加载对应的 messages/${locale}.json。
代理/中间件：Next.js 16 使用 proxy.ts 代替 middleware.ts，API 相同，通过 createMiddleware(routing) 创建，并配置 matcher 排除 /api、/trpc、/_next、/_vercel 以及含点的路径（如 favicon.ico）。
导航辅助：在 src/i18n/navigation.ts 使用 createNavigation(routing)，导出 Link、redirect、usePathname、useRouter、getPathname，使链接保持当前语言。组件中应从 @/i18n/navigation 导入 Link 等，而不是从 next/navigation 或 next/link 导入。
locale 布局与静态渲染：app/[locale]/layout.tsx 需用 hasLocale 校验语言（无效则 notFound）、调用 setRequestLocale(locale) 以支持静态渲染、用 generateStaticParams 生成语言参数，并以 NextIntlClientProvider 包裹 children 并传入 getMessages()。
[locale] 下的页面：为支持静态渲染，每个使用 next-intl 的页面都应调用 setRequestLocale(locale)，必要时使用 use(params)。应在布局/页面中调用任何 next-intl API 之前调用 setRequestLocale。

使用翻译

客户端组件使用 useTranslations(namespace)，链接使用来自 @/i18n/navigation 的 Link。服务端组件则使用 next-intl/server 的 getTranslations（按需传入 locale/namespace）。

消息格式

每种语言在 messages/ 下各有一个 JSON 文件，嵌套键对应命名空间与键，例如 useTranslations("LandingPage") 后可通过 t("title")、t("navbar.about") 取值。支持插值，如 "selectColor": "Select {color} color" 对应 t("selectColor", { color: "Blue" })。

检查清单

文档给出配置检查清单：next.config.ts 由 createNextIntlPlugin() 包裹；routing.ts 定义 locales 与 defaultLocale；request.ts 使用 getRequestConfig + hasLocale + 动态消息；proxy.ts（或 middleware.ts）使用 createMiddleware(routing) 与 matcher；navigation.ts 导出 Link 等；app/[locale]/layout.tsx 完成校验、setRequestLocale、generateStaticParams 与 Provider；每个 page 在使用静态渲染时调用 setRequestLocale；客户端组件使用 useTranslations，链接使用本地化 Link。

参考

examples/ 提供可直接复制的文件，reference.md 提供扩展配置（localePrefix、pathnames 等），并参考 next-intl 官方 App Router 与 Routing setup 文档。

限制

资料中未提及该技能的收费、价格、平台支持范围或效果数据，暂未提供。