# General Translation Knowledge Base: 不使用翻译文件能实现 i18n 吗？
URL: https://generaltranslation.com/zh/kb/i18n-without-translation-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 可以。借助 General Translation 的 gt-react 和 gt-next 库，你可以为 React 和 Next.js 实现 i18n，既无需翻译键，也不用为每种语言维护 JSON 文件。文案以内联方式写在 JSX 的 `<T>` 组件中，gt translate 命令会在构建时结合代码中的上下文，为每种语言生成译文。Locadex 还能通过拉取请求让译文保持最新。
Category: 国际化
Last updated: 2026-10-21
Authors: Jackie Chen, Ernest McCarter
Published: 2026-05-07

可以。借助 General Translation 开源的 `gt-react` 和 `gt-next` 库，你无需翻译键，也不用为每种语言编写 JSON 文件，就能对 React 或 Next.js 应用进行国际化 (i18n) 。只需将文案以内联方式写在 JSX 的 [`<T>`](/docs/react/reference/components/t) 组件中，[`npx gt translate`](/docs/cli/reference/commands/translate) 就会在构建时为每种语言生成译文。

i18next、react-intl 和 next-intl 等基于键的库会在每种语言各自的消息文件中按键查找字符串，因此每新增一个字符串，都要在所有文件中添加对应的键。一旦某个键加到了 `en.json`，却漏掉了 `ja.json`，日文结账页面就会有一行文本没有翻译。

使用 General Translation 时，翻译文件依然存在，只不过是作为构建产物。CLI 会为每种语言生成一个文件，并可将译文发布到 General Translation 的 CDN。没有人需要手动编辑这些文件，也不必在文件之间来回复制键。

## Video

The video is narrated in English, with English captions.

[Can I do i18n without translation files?](https://caxecubb9c64cezv.public.blob.vercel-storage.com/films/kb-i18n-without-translation-files.mp4) (46秒)

General Translation lets you stop writing translation files with `gt-react` or `gt-next`. Run `npx gt init`, write the English inside a `<T>` component, then add `npx gt translate` to your build script so every build writes the translations.

## 能否直接以内联方式翻译 React 组件，而不使用键文件？

可以。使用 General Translation 时，每个句子都保留在组件中，由 [`<T>`](/docs/react/reference/components/t) 包裹，CLI 会翻译整个代码块。相比之下，用 react-i18next 实现的结账摘要需要通过键从 JSON 文件中读取每个字符串：

```json title="locales/en/checkout.json"
{
  "summary": {
    "title": "Order summary",
    "item_count_one": "You have {{count}} item in your cart.",
    "item_count_other": "You have {{count}} items in your cart.",
    "tax_notice": "Tax is calculated at checkout."
  }
}
```

```tsx title="CheckoutSummary.tsx"
import { useTranslation } from 'react-i18next';

export function CheckoutSummary({ itemCount }: { itemCount: number }) {
  const { t } = useTranslation('checkout');
  return (
    <section>
      <h2>{t('summary.title')}</h2>
      <p>{t('summary.item_count', { count: itemCount })}</p>
      <small>{t('summary.tax_notice')}</small>
    </section>
  );
}
```

使用 `gt-next` 编写的同一组件会将英文内容直接保留在 JSX 中。其他 React 框架则从各自对应的软件包导入，例如 `gt-react`。

```tsx title="CheckoutSummary.tsx"
import { T, Plural, Num } from 'gt-next';

export function CheckoutSummary({ itemCount }: { itemCount: number }) {
  return (
    <T>
      <section>
        <h2>Order summary</h2>
        <Plural
          n={itemCount}
          one={<p>You have <Num>{itemCount}</Num> item in your cart.</p>}
          other={<p>You have <Num>{itemCount}</Num> items in your cart.</p>}
        />
        <small>Tax is calculated at checkout.</small>
      </section>
    </T>
  );
}
```

`gt-next` 版本没有 `checkout.json`，不用给键命名，也不用更新 `ja.json`。[`npx gt translate`](/docs/cli/reference/commands/translate) 会将每个 [`<T>`](/docs/react/reference/components/t) 块连同其元素结构一起作为上下文发送到 General Translation API，并为 `gt.config.json` 中配置的每种语言生成翻译。[`<Plural>`](/docs/react/reference/components/plural) 会为每种语言选择所需的复数形式 (日语只有一种，阿拉伯语则有六种) ，而 [`<Num>`](/docs/react/reference/components/num) 会按照读者的区域设置格式化数量。

## 哪些国际化库可以直接在 JSX 中编写文本而无需键文件？

General Translation 的 `gt-react` 和 `gt-next` 让你直接在 JSX 中编写可翻译文本，无需任何键文件，译文由 General Translation 自动生成。Lingui 和 next-intl 的实验性提取功能同样支持内联消息，但它们会将消息提取到消息目录中，之后仍需由你的团队、译者或翻译服务完成翻译。

| 库                                           | 文案编写位置                                                                                                                | 译文来源                                                                            | 团队需要维护的内容                                                   |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| i18next (`react-i18next`)                   | 每种语言各一个 JSON 文件，文案以键的形式存放                                                                                             | 你的团队、译者或翻译服务                                                                    | 在每种语言的文件中为每个字符串维护一个键                                        |
| next-intl                                   | 每种语言各一个 JSON 消息目录，文案以键的形式存放；[通过 `useExtracted` 使用内联消息](https://next-intl.dev/docs/usage/extraction)目前仍为实验性功能            | 你的团队、译者或翻译服务                                                                    | 所有消息目录，并随文案变化及时更新                                             |
| [Lingui](https://lingui.dev/introduction)   | 内联 `<Trans>` 宏，自动生成消息 ID，并提取到 PO 消息目录                                                                                   | 你的团队、译者或翻译服务                                                                    | 提取、翻译和编译消息目录                                                  |
| General Translation (`gt-react`, `gt-next`) | [`<T>`](/docs/react/reference/components/t) 中的内联 JSX、通过 [`useGT`](/docs/react/reference/hooks/use-gt) 处理的字符串，或可选的键控字典 | 每次构建时由 [`npx gt translate`](/docs/cli/reference/commands/translate) 结合代码中的上下文生成 | 用 [`<T>`](/docs/react/reference/components/t) 包裹文案，外加一个构建步骤 |

如果译者或翻译管理系统已经在使用消息目录文件，或者文案很少变动，请选择 i18next 或 next-intl。如果你希望内联编写源文案，并打算将消息目录交给外部翻译，请选择 Lingui 或 next-intl 的提取功能。如果你希望内联编写文案，并在每次构建时自动生成所有语言的译文，请选择 General Translation。偏好稳定键的团队也可以通过 General Translation 的[字典模式](/docs/react/guides/translating-with-dictionaries)继续使用键。

## 基于键的 i18n 与内联翻译各有哪些优缺点？

内联翻译将每个句子保留在渲染它的 React 组件中，因此组件和拉取请求都清晰易读，也无需为键命名、同步或清理。代价是源文案存放在代码中，修改文案必须经过开发者。基于键的 i18n 将文案放在独立于代码的目录中，撰稿人和译者无需改动组件即可工作，但每个字符串都要新增一个键，并在每种语言的文件中添加对应条目。General Translation 两种方式都支持：既可以使用 [`<T>`](/docs/react/reference/components/t) 编写内联文案，也可以使用字典模式配合键。

| 任务        | 翻译键 (i18next、next-intl)                             | 内联文案 (General Translation)                                                                                            |
| --------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| 阅读组件或拉取请求 | 看到的是 `t('summary.tax_notice')`，需要打开 JSON 文件才能找到对应句子 | 直接在 JSX 中看到句子                                                                                                         |
| 添加字符串     | 为键命名并添加到源文件，再同步到每种语言的文件中                            | 写在 [`<T>`](/docs/react/reference/components/t) 内，下一次运行 [`gt translate`](/docs/cli/reference/commands/translate) 时即会翻译 |
| 修改源文案     | 其他语言仍保留旧译文，直到有人更新                                   | 下一次运行会重新翻译已修改的条目                                                                                                      |
| 删除组件      | 其键会一直留在每个文件中，直到有人或脚本将其移除                            | 下一次运行将不再收集其内容                                                                                                         |
| 添加语言      | 创建一个包含所有键的文件并完成翻译                                   | 将区域设置代码添加到 `gt.config.json` 的 `locales` 中，然后运行 [`gt translate`](/docs/cli/reference/commands/translate)               |
| 稳定 ID     | 每个字符串都有                                             | 可选，可在 [`<T>`](/docs/react/reference/components/t) 上使用 [`$id`](/docs/react/reference/components/t#id)，或使用字典模式          |
| 谁来编辑源文案   | 撰稿人可直接编辑目录，无需改动代码                                 | 修改文案就是修改代码                                                                                                            |

如果撰稿人需要在不改动代码的情况下编辑源文案，或者组件中不应包含任何特定语言的句子，那么键更为合适。这种情况下，保留现有的键即可：General Translation 的[字典模式](/docs/react/guides/translating-with-dictionaries)可以读取基于键的字典，同样能生成译文。

## 如何在不使用翻译键的情况下为 Next.js App Router 应用添加多语言支持？

使用 General Translation 的 `gt-next` 库和 `gt` CLI，只需四步即可完成 ([Next.js App Router 快速入门](/docs/react/nextjs-quickstart)中也介绍了手动操作方式) ：

1. 运行 [`npx gt@latest init`](/docs/cli/reference/commands/init)。初始化设置向导会自动检测 App Router，并可安装 `gt-next`、在 `next.config.ts` 中添加 `withGTConfig`、在 `app/layout.tsx` 中添加 [`GTProvider`](/docs/react/reference/components/gt-provider)，同时将你的语言写入 `gt.config.json`。它还可以将开发密钥写入 `.env.local`，这样 `next dev` 就能按需翻译新增文案。请检查向导所做的更改。
2. 用 [`<T>`](/docs/react/reference/components/t) 包裹文案，并添加 [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) 下拉菜单以切换语言。[`<T>`](/docs/react/reference/components/t) 在服务端组件和客户端组件中均可使用。
3. 在构建脚本中，将 [`npx gt translate`](/docs/cli/reference/commands/translate) 放在 `next build` 之前。
4. 在托管服务商处设置 `GT_PROJECT_ID` 和 `GT_API_KEY`。构建所用的密钥需要启用 **Files &gt; Write** 和 **Translation queue** 权限。

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

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

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && next build"
  }
}
```

此后，每次生产环境构建都会为 `gt.config.json` 中配置的每种语言生成译文。如需查看涵盖服务端组件和客户端组件的完整教程，请参阅[如何为 Next.js App Router 应用添加 i18n？](/kb/add-i18n-to-nextjs)。如果想让编程智能体代为完成初始化设置，请参阅[编程智能体工作流](/kb/ai-agent-i18n-setup)。

## 如何避免翻译 JSON 文件与源代码不同步？

不要手动编辑这些文件，而是在每次构建时从源代码生成它们。如果使用键文件，一个包含 400 个字符串、支持 12 种目标语言的应用就有 4,800 个条目，需要有人持续维护以与代码保持一致。使用 General Translation 时，[`npx gt translate`](/docs/cli/reference/commands/translate) 会在构建前运行，收集所有 [`<T>`](/docs/react/reference/components/t) 块和 [`useGT`](/docs/react/reference/hooks/use-gt) 字符串，将新增或更改的内容翻译为 `gt.config.json` 中配置的各个语言，并在 `files.gt.output` 路径下为每种语言写入一个 JSON 文件：

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

```txt title=".gitignore"
public/_gt/
```

由于 General Translation 会在每次构建时根据所编译的代码重新生成这些文件，因此它们始终与代码保持一致。这些文件是自动生成的，因此 Next.js 快速入门会将输出目录添加到 `.gitignore` 中。General Translation 的[增量工作流](/docs/cli/guides/generating-translations#retranslate)只翻译有变更的源内容，并复用早期版本中匹配的译文。[分支跟踪](/docs/cli/guides/branching) (`--enable-branching`，需 Starter 或 Enterprise 方案) 会将功能分支的译文与生产环境隔离，直到该分支合并为止。

如果团队希望将翻译变更提交到代码仓库，可以使用 [Locadex 自动化](/docs/platform/locadex/guides/configuring-automations)：它会通过拉取请求翻译新增或更新的源内容，并在语言列表变化时添加或删除区域设置文件。每个自动化可通过以下三种方式之一触发：拉取请求发生变更、推送提交，或手动启动。有关 CI 配置，请参阅[如何在每次部署时保持译文最新？](/kb/translations-in-ci)。

## General Translation 能否自动为 React 应用添加 i18n？

可以。General Translation 能自动完成 React i18n 的两个步骤：包裹待翻译文案，以及生成译文。

* **构建时：** 在 `gt.config.json` 的 `files.gt.parsingFlags` 下设置 `enableAutoJsxInjection` 后，General Translation 编译器 `@generaltranslation/compiler` 会将可翻译的 JSX 文本包裹在 [`<T>`](/docs/react/reference/components/t) 中。[自动 JSX 注入](/docs/cli/guides/using-auto-jsx)适用于 React 单页应用、服务端渲染的 React 应用以及 Next.js webpack 构建。在 Next.js 中，此编译器工作流需搭配 webpack 使用；如果使用 Turbopack，请直接用 [`<T>`](/docs/react/reference/components/t) 标记内容，或借助 Locadex 添加包裹组件。
* **通过拉取请求：** Locadex 是 General Translation 的 AI 智能体，它会运行 **Generate code** 自动化，将你的源代码包裹在 [`<T>`](/docs/react/reference/components/t) 中，并添加 [`useGT`](/docs/react/reference/hooks/use-gt) 等字符串调用，随后创建拉取请求，供你审查或 auto-merge。
* **生成译文：** 在构建中运行 [`npx gt translate`](/docs/cli/reference/commands/translate)，或使用 Locadex 的 **Generate translations and push** 自动化，即可将新增和变更的内容翻译为所有已配置的语言。

## gt-next 与 next-intl 有何不同？

next-intl 从每种语言各自的 JSON 目录中渲染消息，这些目录由你的团队或第三方服务编写。gt-next 是 General Translation 的 Next.js 库，它将文案以内联方式直接写在 [`<T>`](/docs/react/reference/components/t) 中，并通过 [`gt translate`](/docs/cli/reference/commands/translate) 生成全部译文。两者都支持 App Router 和服务端组件，也都采用 MIT 许可证。

使用 General Translation 无需更换库。`gt` CLI 会根据 `package.json` 检测 next-intl、react-i18next 和 next-i18next，并[翻译它们的 JSON 文件](/docs/cli/guides/generating-translations)，同时保留各个库的消息语法，因此你的组件和路由都无需改动。如果之后想改用内联文案，可参阅[迁移指南](/docs/react/guides/migrating-i18n-libraries)，其中介绍了如何将键替换为 [`<T>`](/docs/react/reference/components/t)、如何借助 [`useTranslations`](/docs/react/reference/hooks/use-translations) 保留字典，以及如何在逐个路由迁移期间让两个库并行运行。如需详细对比，请参阅 [next-intl 与 gt-next 对比](/kb/next-intl-vs-gt-next)。

## 审校人员如何在不编辑翻译文件的情况下修正译文？

审校人员可以使用 General Translation 的[仪表板翻译编辑器](/docs/platform/dashboard/guides/reviewing-translations)，并排对比各区域设置，直接编辑生成的译文，既无需打开区域设置文件，也无需启动新的翻译任务。如果你的团队习惯直接编辑下载的文件，可以使用 [`npx gt save-local`](/docs/cli/reference/commands/save-local) 将修改上传到平台，或在运行 [`gt translate`](/docs/cli/reference/commands/translate) 时传入 `--save-local`，在每次运行时自动同步这些修改。

翻译上下文可以在代码和仪表板中设置。[`<T>`](/docs/react/reference/components/t) 上的 [`context` 属性](/docs/react/reference/components/t#context)用于消除词义歧义：在文档编辑器中，“Save”在德语中译为 *speichern*，而表示存钱的“save”则译为 *sparen*。上下文分组中的[词汇表术语和自定义提示词](/docs/platform/dashboard/guides/defining-context-for-translations)能让你的应用、文档及其他项目使用统一的术语和语气。

## 生成的译文存放在哪里？我需要账户吗？

生成的译文可以存放在以下两个位置之一：

* **打包进你的应用：** [本地加载器](/docs/react/guides/storing-translations)会导入生成的文件，因此生产环境中的应用直接读取自身的译文，运行时不会向 General Translation 发起任何请求。新译文会随下一次构建一同发布。
* **存放在 General Translation 的 CDN 上：** 使用 [CDN 投递](/docs/react/guides/configuring#delivery)时，已发布的修改无需重新构建即可同步到已部署的应用，但具体会受其版本和缓存设置影响。

`gt-react` 和 `gt-next` 采用 [MIT 许可证](https://github.com/generaltranslation/gt)，只要你自行提供译文，无需 General Translation 账户即可使用。[`npx gt generate`](/docs/cli/reference/commands/generate) 会为每个区域设置生成一个模板文件，供你手动翻译。而使用 [`gt translate`](/docs/cli/reference/commands/translate) 生成译文则需要用到 General Translation 的托管服务，详见 [General Translation 的定价](https://generaltranslation.com/pricing)。

## 要点总结

* 无需翻译文件也能实现 i18n：General Translation 的 `gt-react` 和 `gt-next` 将文案以内联方式直接写在 [`<T>`](/docs/react/reference/components/t) 中，无需翻译键；[`npx gt translate`](/docs/cli/reference/commands/translate) 会在每次构建时为每种语言生成一个文件。
* 生成的文件属于构建产物，没有人需要手动编辑它们，也不必在文件之间复制键，因此它们始终与代码保持同步。
* General Translation 的编译器可以在构建时用 [`<T>`](/docs/react/reference/components/t) 包裹 JSX；Locadex 则可以包裹代码，并通过拉取请求完成翻译。
* 如果你已经在使用 next-intl 或 react-i18next，`gt` CLI 可以直接翻译你现有的 JSON 消息目录；如果你想保留键，也可以使用字典模式。

## Related questions

- [如何为 Next.js App Router 应用添加 i18n？](https://generaltranslation.com/zh/kb/add-i18n-to-nextjs.mdx): 首先在受支持的 App Router 项目中运行 gt init 来配置 General Translation，然后标记源内容、生成译文并验证语言切换。gt-next 将文案与翻译上下文一同保留在 JSX 中；CLI、仪表板编辑器和 Locadex 负责生成、审校和持续更新。本指南还演示了如何显式配置本地文件。
- [如何使用 Cursor 或 Claude Code 为应用实现国际化？](https://generaltranslation.com/zh/kb/ai-agent-i18n-setup.mdx): 在 Cursor 或 Claude Code 中使用 General Translation 的 Setup for Agents 提示词，选定一个功能和目标语言，然后让智能体完成实现并验证结果。借助浏览器登录、机器可读文档和 MCP 工具，初始化设置可以与翻译和审校环节无缝衔接。使用 Locadex，即可通过拉取请求自动完成后续的持续本地化工作。
- [如何在 React 中处理复数形式？](https://generaltranslation.com/zh/kb/how-to-handle-plurals-in-react.mdx): 在 React 中处理复数形式时，应为每种语言的每个复数形式各准备一个句子，并按该语言的复数规则选出对应句子——英语有 2 种形式，俄语有 4 种，阿拉伯语有 6 种。gt-react 和 gt-next 提供的 General Translation `<Plural>` 组件只需接收你的源语言形式，General Translation 便会生成每种目标语言所需的形式。
- [如何在每次部署时保持译文同步更新？](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: [面向开发者的最佳本地化软件是什么？](https://generaltranslation.com/zh/kb/best-localization-software.mdx)
- Next question: [Crowdin 替代方案：General Translation 与 Crowdin 对比](https://generaltranslation.com/zh/kb/general-translation-vs-crowdin.mdx)

## Sitemap

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