Next.js 应用路由国际化 (i18n)

想看视频教程吗？

开始入门

如果你还没有这样做，创建一个使用 App Router 的 Next.js 应用，然后运行：

npm install next-intl

现在，我们将创建以下文件结构：

├── messages
│   ├── en.json
│   └── ...
├── next.config.ts
└── src
    ├── i18n
    │   └── request.ts
    └── app
        ├── layout.tsx
        └── page.tsx

让我们来设置这些文件：

`messages/en.json`

Messages 代表每种语言可用的翻译，可以是本地提供，也可以从远程数据源加载。

最简单的做法是将 JSON 文件添加到你的本地项目文件夹：

messages/en.json

{
  "HomePage": {
    "title": "你好，世界！"
  }
}

`i18n/request.ts`

next-intl 会创建一个请求作用域的配置对象，你可以使用它基于用户的语言环境为服务器组件提供消息和其他选项。

src/i18n/request.ts

import {getRequestConfig} from 'next-intl/server';
 
export default getRequestConfig(async () => {
  // 目前是静态的，稍后会更改
  const locale = 'en';
 
  return {
    locale,
    messages: (await import(`../../messages/${locale}.json`)).default
  };
});

我可以把这个文件放到别的地方吗？

此文件在 src 目录下以及项目根目录中以 .ts、.tsx、.js 和 .jsx 扩展名存在时，均可开箱即用，路径为 ./i18n/request.ts。

如果你想将此文件放到其他位置，可以选择性地向插件提供路径：

next.config.ts

const withNextIntl = createNextIntlPlugin(
  // 在这里指定自定义路径
  './somewhere/else/request.ts'
);

`next.config.ts`

现在设置插件，将你的 i18n/request.ts 文件链接到 next-intl。

next.config.ts

import {NextConfig} from 'next';
import createNextIntlPlugin from 'next-intl/plugin';
 
const nextConfig: NextConfig = {};
 
const withNextIntl = createNextIntlPlugin();
export default withNextIntl(nextConfig);

`app/layout.tsx`

为了让你的请求配置在客户端组件中可用，可以用 NextIntlClientProvider 包裹根布局中的 children。

app/layout.tsx

import {NextIntlClientProvider} from 'next-intl';
 
type Props = {
  children: React.ReactNode;
};
 
export default async function RootLayout({children}: Props) {
  return (
    <html>
      <body>
        <NextIntlClientProvider>{children}</NextIntlClientProvider>
      </body>
    </html>
  );
}

`app/page.tsx`

在页面组件或其他任何地方使用翻译！

app/page.tsx

import {useTranslations} from 'next-intl';
 
export default function HomePage() {
  const t = useTranslations('HomePage');
  return <h1>{t('title')}</h1>;
}

对于异步组件，则可以使用可等待的 getTranslations 函数：

app/page.tsx

import {getTranslations} from 'next-intl/server';
 
export default async function HomePage() {
  const t = await getTranslations('HomePage');
  return <h1>{t('title')}</h1>;
}

后续步骤

基于语言环境的路由

如果你想为应用支持的每种语言使用唯一的路径名（例如 /en/about 或 example.de/über-uns），可以继续为应用设置顶层的 [locale] 路由段。

设置基于语言环境的路由→

提供语言环境

如果你的应用不需要为每个语言环境使用唯一路径名，可以基于用户偏好或其他应用逻辑向 next-intl 提供语言环境。

最简单的做法是使用 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
    // ...
  };
});

国际化不只是翻译文字

next-intl 提供 Next.js 应用国际化的基础设施。它处理翻译、日期和数字格式化，以及国际化路由等方面。

然而，为全球用户构建应用涵盖更广泛的内容：

为你的应用选择合适的 架构和路由策略
集成 后端服务或 CMS
利用 生成式 AI 进行内容本地化
通过 TypeScript 和 IDE 工具优化 开发工作流
使用 翻译管理系统 进行团队协作
理解构建 真正本地化体验 所需的各个部分
掌握多语言应用的 SEO 优化，以触达全球用户

自信构建国际化 Next.js 应用

Learn how to build delightful, multilingual apps with Next.js—from the basics to advanced patterns, all through a real-world project.

Get started→

入门 Pages Router