next-intl 文档技能

next-intl 4

本技能涵盖 next-intl 4.x，文档来源为 https://next-intl.dev/docs/getting-started（文档版本 4.14.9）。它记录了与习惯用法不同的地方：令人惊讶的默认值、陷阱、旧版 API 以及文档推荐的模式。参考文件中的每条声明末尾都注明了来源页面。

如何导航

1. 阅读下面的快速入门和快速规则。它们能帮你避免最常见的错误。
2. 根据任务，从末尾的表格中打开对应的参考文件。
3. 当代码中使用了 setRequestLocale、requestLocale 或 middleware.ts 时，先阅读“旧模式”表格。

快速入门（App Router）

App Router 是推荐路径。Pages Router 仍然受支持，请参阅 references/setup.md。https://next-intl.dev/docs/getting-started/pages-router

// next.config.ts
import {NextConfig} from 'next';
import createNextIntlPlugin from 'next-intl/plugin';

const nextConfig: NextConfig = {};
const withNextIntl = createNextIntlPlugin();
export default withNextIntl(nextConfig);

https://next-intl.dev/docs/getting-started/app-router

如果没有基于语言环境的 URL，src/i18n/request.ts 会从用户偏好解析语言环境，最简单的方式是通过 cookie：

// src/i18n/request.ts
import {cookies} from 'next/headers';
import {getRequestConfig} from 'next-intl/server';

export default getRequestConfig(async () => {
  const store = await cookies();
  const locale = store.get('locale')?.value || 'en';
  return {
    locale,
    messages: (await import(`../../messages/${locale}.json`)).default
  };
});

https://next-intl.dev/docs/getting-started/app-router

// src/app/layout.tsx
import {NextIntlClientProvider} from 'next-intl';
import {getLocale} from 'next-intl/server';

export default async function RootLayout({children}) {
  const locale = await getLocale();
  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider>{children}</NextIntlClientProvider>
      </body>
    </html>
  );
}

https://next-intl.dev/docs/getting-started/app-router , https://next-intl.dev/docs/usage/configuration

import {useTranslations} from 'next-intl';
import {getTranslations} from 'next-intl/server';

export function HomePage() {
  const t = useTranslations('HomePage'); // 非异步组件
  return <h1>{t('title')}</h1>;
}

export async function Profile() {
  const t = await getTranslations('ProfilePage'); // 异步组件
  return <h1>{t('title')}</h1>;
}

https://next-intl.dev/docs/getting-started/app-router

对于 /en/about 样式的 URL，添加 src/i18n/routing.ts、src/proxy.ts、src/i18n/navigation.ts 和一个顶层 [locale] 段：references/routing.md。https://next-intl.dev/docs/routing/setup

快速规则

设置

• 插件会在 src/ 或项目根目录下查找 i18n/request.ts（.ts、.tsx、.js、.jsx）。如果在其他位置，请传递路径：createNextIntlPlugin('./somewhere/else/request.ts')。https://next-intl.dev/docs/getting-started/app-router
• 文档示例中硬编码了 const locale = 'en'。请替换为真实的解析逻辑（cookie、用户设置或 next/root-params）。https://next-intl.dev/docs/getting-started/app-router
• getRequestConfig 在每个请求中运行一次，在 Server Components 渲染阶段，因此 cookies() 和 headers() 在此处可用。https://next-intl.dev/docs/usage/configuration
• 在请求配置中设置 timeZone。默认值是服务器运行时的时区。https://next-intl.dev/docs/usage/configuration

路由

• 在 Next.js 16 上，将文件命名为 src/proxy.ts。导入方式不变：createMiddleware 来自 next-intl/middleware。https://next-intl.dev/docs/routing/setup
• 使用 next/root-params 中的 await rootParams.locale() 读取语言环境，用 hasLocale(routing.locales, value) 验证，否则调用 notFound()。Next.js 16.3 之前的版本需要 experimental.rootParams。https://next-intl.dev/docs/routing/setup
• 从你的 i18n/navigation.ts 中导入 Link、redirect、usePathname、useRouter 和 getPathname，而不是从 next/link 或 next/navigation。https://next-intl.dev/docs/routing/navigation
• 使用该模块中的 router.replace(pathname, {locale}) 来切换语言环境。<Link locale> 不会被预取，以避免覆盖语言环境 cookie。https://next-intl.dev/docs/routing/navigation
• redirect 始终接受一个语言环境：redirect({href: '/login', locale})。为了 TypeScript 的类型收窄，请使用 return redirect(...)。https://next-intl.dev/docs/routing/navigation
• 默认的匹配器会跳过包含点的路径。对于像 /users/jane.doe 这样的路由，请添加显式条目。https://next-intl.dev/docs/routing/middleware

客户端组件

• 不带 messages 属性的 NextIntlClientProvider 会将所有消息发送到客户端。传递 messages={pick(messages, 'Namespace')} 或 messages={null} 来限制它们。https://next-intl.dev/docs/environments/server-client-components
• 优先在 Server Component 中翻译，并将标签作为 props 或 children 传递给 Client Component。https://next-intl.dev/docs/environments/server-client-components
• onError 和 getMessageFallback 不能从 Server Component 传递。在你的 'use client' 提供商中设置它们，该提供商嵌套在服务器提供商内部，自动继承语言环境和消息，因此不要手动传递这些。https://next-intl.dev/docs/usage/configuration

消息

• 键和命名空间不能包含 .，这意味着嵌套。只能使用嵌套的 JSON。https://next-intl.dev/docs/usage/translations
• ICU 参数名称和 select 值允许字母、数字和 _，不能有破折号：将 en-GB 映射为 en_GB。select 需要一个 other 分支。https://next-intl.dev/docs/usage/translations
• 自闭合标签在消息中需要一个闭合标签：<br></br>。https://next-intl.dev/docs/usage/translations
• 在 Server Actions、metadata 和 Route Handlers 中使用 getTranslations({locale, namespace})，因为在这些环境中语言环境可能无法推断。https://next-intl.dev/docs/environments/actions-metadata-route-handlers

测试

• Vitest 配合 createNavigation：使用 server.deps.inline: ['next-intl']。Jest：使用 transformIgnorePatterns: ['node_modules/(?!next-intl)/']。next-intl 仅支持 ESM。https://next-intl.dev/docs/environments/testing

旧模式

旧模式	当前模式
src/middleware.ts	在 Next.js 16 上为 src/proxy.ts，createMiddleware 代码相同
在每个布局和页面顶部使用 setRequestLocale(locale)	在 i18n/request.ts 中使用 next/root-params，静态渲染无需此操作
getRequestConfig(async ({requestLocale}) => ...)	getRequestConfig(async ({locale}) => ...) 并回退到 rootParams.locale()
扁平消息键 "HomePage.title"	嵌套对象 {"HomePage": {"title": ...}}
在 dangerouslySetInnerHTML 中使用 t.raw HTML	使用 t.rich（React）或 t.markup（字符串），t.raw 仅用于跳过解析，已清理

详细信息：references/routing.md 和 references/messages.md。

参考文件

文件	适用场景
references/setup.md	插件、请求配置、供应商默认值、无路由的语言环境、消息存储、Pages Router
references/routing.md	defineRouting、[locale] 段、proxy.ts、匹配器、next/root-params、静态渲染、localePrefix、域名、cookie、备用链接、本地化路径名、静态导出、故障排除
references/navigation.md	createNavigation、Link、useRouter、usePathname、redirect、getPathname、语言切换器、类型安全的 href
references/messages.md	useTranslations、命名空间、ICU 复数和选择、富文本、t.markup、t.raw、t.has、数组、缺失消息、onError、时区、now
references/formatting.md	useFormatter：日期、相对时间、范围、数字、列表、显示名称、ICU 骨架、全局格式
references/server-and-client.md	服务端与客户端组件、挑选消息、元数据、Server Actions、Zod、Route Handlers、站点地图、OG 图片、404 和错误文件
references/extraction.md	实验性 useExtracted 和 getExtracted、插件 experimental 选项、PO 文件、预编译、自定义编解码器、单体仓库
references/typescript-and-tooling.md	AppConfig 增强、类型安全参数、Jest 和 Vitest 测试、Storybook、use-intl 核心、运行时要求、linting、翻译管理、代理约定

已爬取页面：SOURCES.md。