# General Translation Knowledge Base: 如何为 Next.js App Router 应用添加 i18n？
URL: https://generaltranslation.com/zh/kb/add-i18n-to-nextjs.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 首先在受支持的 App Router 项目中运行 gt init 来配置 General Translation，然后标记源内容、生成译文并验证语言切换。gt-next 将文案与翻译上下文一同保留在 JSX 中；CLI、仪表板编辑器和 Locadex 负责生成、审阅和持续更新。本指南还演示了如何显式配置本地文件。
Category: 国际化
Last updated: 2026-10-21
Authors: Kevin Liu, Kevin Wu
Published: 2026-10-21

本教程将为一个小型项目页面添加英语、西班牙语和法语支持，涵盖服务端组件、客户端组件和语言切换器。教程采用基于 cookie 的语言选择方式；带区域设置前缀的 URL 和多语言 SEO 需另行配置。

General Translation 的 `gt-next` 专为 Next.js App Router 打造。它将源文案保留在赋予其含义的 JSX 中，并将这些内容接入译文生成流程。可使用 [`context` 属性](/docs/react/reference/components/t#context)说明有歧义的措辞，并配置[词汇表术语和自定义提示词](/docs/platform/dashboard/guides/defining-context-for-translations)来控制术语和语气。之后，下文介绍的构建工作流会在源内容变更时自动更新译文。

## Video

The video is narrated in English, with English captions.

[How do I add i18n to a Next.js app?](https://caxecubb9c64cezv.public.blob.vercel-storage.com/films/kb-add-i18n-to-nextjs.mp4) (51秒)

General Translation lets you add i18n with `gt-next`: wrap text in `T` and generate translations. Wrap your config in `withGTConfig`, list your languages, add a `loadTranslations` file, put the `GTProvider` in your root layout, add a `<LocaleSelector>` for the menu, and run `npx gt translate` before `next build`.

## 开始之前

请准备一个现有的 TypeScript App Router 项目，且包含 `src/app` 目录。示例基于 Next.js 16，并使用 npm。Next.js 16 需要 Node.js 20.9 或更高版本。如果你要从零开始，请先参照 [Next.js 安装指南](https://nextjs.org/docs/app/getting-started/installation)完成安装。Pages Router 应用请参阅 [Pages Router 快速入门](/docs/react/nextjs-pages-router-quickstart)。

本示例显式指定了 `gt-next@11.4.12` 和 `gt@2.26.5`。该库采用 MIT 许可证，无需账户即可渲染你自行提供的译文。如需使用服务生成的译文，请使用 GT 项目，并通过 [CLI 登录或限定作用域的工具密钥](/docs/cli/guides/configuring#credentials)完成认证。自动化构建请使用 CI 密钥存储中的密钥。

## 从初始化设置命令开始

在应用目录中运行初始化设置向导：

```bash
npx gt@2.26.5 init
```

为你的 App Router 应用选择 React 框架初始化设置、源语言和目标语言，以及本地或 CDN 投递方式。向导会安装 `gt-next`，添加 [`GTProvider`](/docs/react/reference/components/gt-provider) 和 [`withGTConfig`](/docs/react/nextjs/config)，并创建 `gt.config.json`。如果选择本地投递，它还会创建一个翻译加载器。框架改写功能目前仍处于实验阶段，请务必检查生成的差异，尤其是涉及现有提供者和配置包装器的部分。[初始化设置参考](/docs/cli/reference/commands/init)。

标记应用内容和生成翻译仍需由你完成。如果你希望由编程智能体全程执行该任务直至完成验证，请使用 [Setup for Agents](https://generaltranslation.com/agent-prompt.md)。

下面的显式初始化设置使用 `src/_gt/[locale].json`，而向导默认的本地输出路径为 `public/_gt/[locale].json`。请确保向导生成的加载器与其输出路径配套使用，或者完整采用下面的显式初始化设置作为替代方案。

## 显式配置库并编写页面

### 1. 安装 SDK 和 CLI

在应用目录中运行以下命令：

```bash
npm install gt-next@11.4.12
npm install --save-dev gt@2.26.5
```

`gt-next` 负责在应用中渲染译文。`gt` 是用于收集和翻译源内容的命令行工具。[官方 Next.js 快速入门](/docs/react/nextjs-quickstart)。

### 2. 配置 Next.js 和语言

使用 [`withGTConfig`](/docs/react/nextjs/config) 包裹现有的 Next.js 配置。请保留原有设置，并将其与您正在使用的其他配置包装器结合使用。

```ts title="next.config.ts"
import { withGTConfig } from 'gt-next/config';

export default withGTConfig({});
```

在项目根目录下创建此文件：

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json"
    }
  }
}
```

英语是源语言，西班牙语和法语是目标语言。输出路径用于告诉 CLI 应将生成的译文写入何处。

### 3. 添加本地翻译加载器

创建 `src/loadTranslations.ts`。配置插件会自动检测到该文件，并通过它加载生成的区域设置文件：

```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  const translations = await import(`./_gt/${locale}.json`);
  return translations.default;
}
```

此初始化设置会将译文打包进应用包，因此在生产环境中，这部分内容无需在运行时调用 General Translation。译文更新会随构建一同发布。参见[本地翻译存储](/docs/react/guides/storing-translations)。

这些文件目前尚不存在。请先完成页面编写，并在第 6 步中生成这些文件，再启动开发服务器；否则加载器的 import 可能会失败。

### 4. 将提供者添加到根布局

参照以下示例修改 `src/app/layout.tsx`，并保留现有的样式、字体、元数据及其他提供者。

```tsx title="src/app/layout.tsx"
import type { PropsWithChildren } from 'react';
import { GTProvider } from 'gt-next';
import { getLocale } from 'gt-next/server';

export default async function RootLayout({ children }: PropsWithChildren) {
  const locale = await getLocale();

  return (
    <html lang={locale}>
      <body>
        <GTProvider>{children}</GTProvider>
      </body>
    </html>
  );
}
```

[`getLocale`](/docs/react/nextjs/reference/functions/get-locale) 在服务器端解析当前语言。[`GTProvider`](/docs/react/reference/components/gt-provider) 为整个应用 (包括其中的交互式组件) 提供翻译上下文。

### 5. 翻译 JSX 和输入框属性

添加如下页面，它仍然是一个服务端组件。[`T`](/docs/react/reference/components/t) 会将静态标题和段落标记为待翻译内容；[`LocaleSelector`](/docs/react/reference/components/locale-selector) 则提供语言下拉菜单。

```tsx title="src/app/page.tsx"
import { LocaleSelector, T } from 'gt-next';
import SearchBox from './SearchBox';

export default function Home() {
  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>Find your next project</h1>
        <p>Explore projects from teams around the world.</p>
      </T>
      <SearchBox />
    </main>
  );
}
```

将搜索输入框创建为客户端组件。对于字符串值属性 (例如占位符和无障碍标签) ，请使用 [`useGT`](/docs/react/reference/hooks/use-gt)：

```tsx title="src/app/SearchBox.tsx"
'use client';

import { useGT } from 'gt-next';

export default function SearchBox() {
  const gt = useGT();

  return (
    <input
      type='search'
      placeholder={gt('Search projects')}
      aria-label={gt('Search projects')}
    />
  );
}
```

[`useGT()`](/docs/react/reference/hooks/use-gt) 会直接返回翻译函数。在异步服务端组件中，请改用 `gt-next/server` 中的 [`getGT`](/docs/react/nextjs/reference/functions/get-gt)。

不要将动态值直接写在 [`T`](/docs/react/reference/components/t) 内部的原始表达式中。如需插入名称、数量或分支，请使用相应的[变量和格式化组件](/docs/react/guides/formatting-variables)。

## 生成译文并验证结果

### 6. 生成翻译输出

如需自动翻译，请使用 [`gt login`](/docs/cli/reference/commands/login) 登录并配置项目 ID，或者在 `.env.local` 中设置项目 API 密钥和项目 ID：

```bash title=".env.local"
GT_PROJECT_ID="your-project-id"
GT_API_KEY="your-project-api-key"
```

请妥善保管该密钥，切勿将该文件提交到版本控制中。不要通过 `NEXT_PUBLIC_` 变量暴露 `GT_API_KEY`。工具链所用的密钥需要具备文件读写和翻译队列权限；如需使用上下文，还需具备上下文访问权限。详情请参阅 [API 密钥文档](/docs/platform/dashboard/reference/api-keys)。

生成译文：

```bash
npx gt translate
```

该命令会将翻译任务提交至 General Translation，并将区域设置文件写入配置的输出路径。你可以在[仪表板翻译编辑器](/docs/platform/dashboard/guides/reviewing-translations)中审阅生成的文本。如果你在本地修改了下载的译文，可以使用 [`gt save-local`](/docs/cli/reference/commands/save-local) 将这些更正同步回平台。通过该服务生成译文采用[按用量计费](https://generaltranslation.com/pricing)。

如果你想先试用该库而不调用翻译服务，请改为运行以下命令：

```bash
npx gt generate
```

[`gt generate`](/docs/cli/reference/commands/generate) 会创建包含源文本的模板，但**不会翻译这些文本**。请编辑 `src/_gt/es.json` 和 `src/_gt/fr.json` 中的文本值，同时保留生成的键和 JSX 结构。例如，将西班牙语标题翻译为“Encuentra tu próximo proyecto”，将搜索标签翻译为“Buscar proyectos”。其余文本也需全部翻译完毕，这些文件才算完成。

修改源内容后，请重新运行 [`gt generate`](/docs/cli/reference/commands/generate)，并检查目标文件。该命令会保留已有的目标值，以源文本形式添加新条目，并删除源中已不存在的条目。

### 7. 启动应用并切换语言

```bash
npm run dev
```

打开 Next.js 输出的地址。在下拉菜单中分别选择西班牙语和法语，确认标题、段落、占位符以及输入框的无障碍标签都随之切换。重新加载页面，检查所选语言是否得以保留，然后切换回英语。

如果选择器已切换但文本仍显示为英语，请检查目标语言文件。由 [`gt generate`](/docs/cli/reference/commands/generate) 生成的源模板在翻译之前仍是英语内容。如果页面因缺少区域设置文件而无法编译，请先重新运行相应的生成命令，再重启开发服务器。

## 为生产环境构建

在发起托管翻译请求之前，先运行 [`gt validate`](/docs/cli/reference/commands/validate) 捕获翻译语法错误。GT 的 [ESLint 规则](/docs/react/guides/linting-your-code)还能在开发阶段提供额外检查。[配置开发阶段翻译](/docs/react/guides/configuring#delivery)后，你还可以在编辑时预览已翻译内容。

如需使用自动翻译工作流，请将以下构建命令合并到现有的 `package.json` scripts 中：

```json
{
  "scripts": {
    "build": "gt validate && gt translate && next build"
  }
}
```

在构建环境中设置 `GT_PROJECT_ID` 和 `GT_API_KEY`。确保以开发依赖形式安装的 CLI 在构建过程中可用。如果每次构建都会重新生成翻译输出，请将 `src/_gt/` 添加到 `.gitignore`。

如果你选择了手动翻译，请将翻译后的文件纳入版本控制，或从你自己的翻译流水线中获取。待这些文件就绪后，再运行 `next build`。不要把手动维护的译文当作可重新生成的输出而忽略，否则可能丢失其唯一副本。

构建完成后，运行生产环境应用并再次检查语言切换。这样测试的是实际要发布的文件，而不仅仅依赖开发环境下的行为。

[增量翻译工作流](/docs/cli/guides/generating-translations#retranslate)会翻译有变更的源内容，并复用早期版本中匹配的译文。如需同时自动处理代码仓库的变更，可以配置 [Locadex](/docs/platform/locadex/guides/configuring-automations)，通过拉取请求对新增 UI 进行国际化、生成译文或同步区域设置变更。请根据你的发布流程选择合适的触发和审核设置。

如果希望更新译文时无需重新构建应用，请选择 [CDN 投递](/docs/react/nextjs/config)，而非本地加载器。这样，已发布的译文修改即可按照已部署应用的版本和缓存设置生效。

如果公开页面需要按语言使用独立的 URL，请继续阅读 [App Router 区域设置路由](/docs/react/nextjs/app-router-middleware)。此处基于 cookie 的示例不会创建 `/es` 和 `/fr` 页面，也不会配置规范网址和 `hreflang` 元数据。

## 供编程智能体使用的提示词

先使用持续维护的[官方初始化设置提示词](https://generaltranslation.com/agent-prompt.md)，再附上以下功能说明：

```text
以英语为源语言，西班牙语和法语为目标语言。
使用本地随应用打包的译文对项目页面进行本地化。保留
现有的提供者和路由。本地化范围包括页面的标题、段落、搜索输入框、
无障碍标签，并添加语言选择器。使用项目的共享术语。
验证语言切换、重新加载后语言设置是否保持、服务器端渲染的内容、
客户端属性以及生产环境构建。报告实际测试了哪些内容，
以及哪些内容仍需进行语言审校。不要部署或合并。
```

如需了解完整的工作流，请参阅[无需翻译文件的 i18n](/kb/i18n-without-translation-files)和[使用编程智能体](/kb/ai-agent-i18n-setup)。

## Related questions

- [不使用翻译文件能实现 i18n 吗？](https://generaltranslation.com/zh/kb/i18n-without-translation-files.mdx): 可以。借助 General Translation 的 gt-react 和 gt-next 库，你可以为 React 和 Next.js 实现 i18n，既无需翻译键，也不用为每种语言维护 JSON 文件。文案以内联方式写在 JSX 的 `<T>` 组件中，gt translate 命令会在构建时结合代码中的上下文，为每种语言生成译文。Locadex 还能通过拉取请求让译文保持最新。
- [如何使用 Cursor 或 Claude Code 为应用实现国际化？](https://generaltranslation.com/zh/kb/ai-agent-i18n-setup.mdx): 在 Cursor 或 Claude Code 中使用 General Translation 的 Setup for Agents 提示词，选定一个功能和目标语言，然后让智能体完成实现并验证结果。借助浏览器登录、机器可读文档和 MCP 工具，初始化设置可以与翻译和审校环节无缝衔接。使用 Locadex，即可通过拉取请求自动完成后续的持续本地化工作。
- [如何在每次部署时保持译文同步更新？](https://generaltranslation.com/zh/kb/translations-in-ci.mdx): 在每次生产环境构建之前，将翻译作为流水线中的一个步骤运行，这样新增文案就会在引入它的那次部署中以翻译好的形式一同上线。General Translation 的 gt CLI 通过 npx gt translate 实现这一点，所需的项目 API 密钥和项目 ID 以 CI 密钥的形式存储。

## Previous and next questions

- Previous question: [Locadex 智能体能做什么？](https://generaltranslation.com/zh/kb/what-is-locadex.mdx)
- Next question: [如何使用 Cursor 或 Claude Code 为应用实现国际化？](https://generaltranslation.com/zh/kb/ai-agent-i18n-setup.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/zh/kb/sitemap.md) for every article.