# General Translation Knowledge Base: 如何使用 Cursor 或 Claude Code 为应用实现国际化？
URL: https://generaltranslation.com/zh/kb/ai-agent-i18n-setup.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 在 Cursor 或 Claude Code 中使用 General Translation 的 Setup for Agents 提示词，选定一个功能和目标语言，然后让智能体完成实现并验证结果。借助浏览器登录、机器可读文档和 MCP 工具，初始化设置可以与翻译和审校环节无缝衔接。使用 Locadex，即可通过拉取请求自动完成后续的持续本地化工作。
Category: 国际化
Last updated: 2026-10-21
Authors: Kevin Liu, Kevin Wu
Published: 2026-10-21

“把我的应用翻译成西班牙语”——这句话背后还有好几个问题没有答案：智能体是否应保留现有的库？西班牙语是否需要独立的 URL？本次会话结束后，新增文案由谁来翻译？在让智能体改动应用之前，请先划定这些边界。

General Translation 提供了一份持续维护的初始化设置提示词，引导编程智能体依次完成项目检查、集成、翻译和验证。先让一个功能跑通，再将验证过的模式推广到整个代码库。

## Video

The video is narrated in English, with English captions.

[Can an AI coding agent set up i18n for me?](https://caxecubb9c64cezv.public.blob.vercel-storage.com/films/kb-ai-agent-i18n-setup.mp4) (46秒)

General Translation lets your agent set up i18n with the prompt from Setup for Agents. The prompt has the agent run `gt login`, which you approve in your browser, and run `gt init` with a flag for every question, so the command asks nothing. Then it wraps your page in the `T` component, adds a `LocaleSelector`, runs `gt translate`, builds the app and reports what it actually verified.

## 从 Setup for Agents 开始

在 generaltranslation.com 上使用 **Setup for Agents**，或者将[官方智能体提示词](https://generaltranslation.com/agent-prompt.md)提供给 Cursor 或 Claude Code。该提示词会引导智能体检查你的项目，并遵循最新的框架说明。对于受支持的项目，[`gt init`](/docs/cli/reference/commands/init) 提供实验性的框架初始化设置；随后智能体会审查生成的集成代码、标记内容、生成译文并验证应用。

如需在本地访问服务，可使用 [`gt login`](/docs/cli/reference/commands/login) 在浏览器中批准登录，无需将 API 密钥粘贴到聊天中。不过，CLI 仍需选定或配置好目标项目。初始化设置标志可以在没有交互式终端的情况下回答向导中的问题，但首次登录仍需你亲自批准。对于无人值守的构建，请使用 CI 密钥存储中限定权限范围的凭据。

智能体可以通过 [`llms.txt`](https://generaltranslation.com/llms.txt) 发现文档，在文档 URL 后追加 `.mdx` 获取纯净的源内容，并查阅 [OpenAPI 规范](https://generaltranslation.com/openapi.yaml)。[编码智能体指南](/docs/overview/for-coding-agents)提供了可复用的项目说明。这些资源均持续维护，可确保初始化设置始终与当前产品 API 保持一致。[文档设计文章](/blog/rewriting-our-docs)介绍了这些文档发现入口的工作原理。

## 为智能体分配边界明确的任务

让它检查框架、已安装的版本、渲染模型、路由、现有的 i18n 配置以及构建脚本。如果应用已在使用某个国际化库，除非任务本身包含迁移，否则应保留该库。GT 的 CLI 可以[翻译受支持的现有消息目录](/docs/cli/guides/generating-translations)，包括 next-intl 和 react-i18next。

明确指定源语言、目标区域设置以及要修改的功能。验证消息、占位符、无障碍标签和元数据也要一并纳入。选择本地投递或 CDN 投递，并指定由谁在[仪表板翻译编辑器](/docs/platform/dashboard/guides/reviewing-translations)中审核结果。

## 连接 General Translation 的 MCP 服务器

General Translation 托管的 [Model Context Protocol (MCP) 服务器](/docs/overview/for-coding-agents#mcp) 让你的编程智能体能够查看实时项目设置并管理翻译上下文。智能体可以查询项目的区域设置、读取共享术语，并在任务需要时更新词汇表术语或自定义提示词。这样，代码变更就能与团队在 General Translation 中维护的翻译规则保持一致。

借助以下工具，该连接可端到端地支持整个翻译工作流：

* 翻译内容、上传源文件、将翻译任务加入队列、检查状态以及下载结果。
* 在 CDN 上发布或取消发布译文。
* 查找和创建项目，并在获得授权时创建限定作用范围的项目 API 密钥。
* 管理上下文组、词汇表术语和自定义提示词。

请根据你希望智能体执行的工作流授予相应权限。生成的密钥应保存在受保护的密钥存储中，切勿放在聊天记录或浏览器代码中。翻译生成会调用该服务并按用量计费；应用的本地提取和翻译流程则由下方的 CLI 负责处理。

在 **Cursor** 中，将此服务器条目添加到项目的 `.cursor/mcp.json` 中，并保留所有现有条目。有关配置和认证选项，请参阅 [Cursor 的 MCP 设置](https://cursor.com/docs/mcp)。

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "generaltranslation": {
      "url": "https://api.gtx.dev/mcp"
    }
  }
}
```

在 **Claude Code** 中，通过其 [HTTP 传输方式](https://code.claude.com/docs/en/mcp)注册同一个服务器：

```bash
claude mcp add --transport http generaltranslation https://api.gtx.dev/mcp
```

完成客户端的 OAuth 登录流程，或按照 [MCP 身份验证指南](/docs/overview/for-coding-agents#mcp)中的说明，在客户端的密钥请求头设置中配置 API 密钥。Context Management 需要 Organization Context 访问权限，可通过 OAuth 或具备相应 Context 权限的组织密钥获得；项目密钥无法访问这些工具。

先从一个具体的请求入手：“使用 generaltranslation MCP 服务器列出我的项目，并显示我们正在本地化的项目的区域设置。”然后让智能体查看该项目已分配的上下文组，其中包含共享的词汇表术语和自定义提示词。智能体在开发该功能时可以参考这些术语和指令，并在你要求调整术语或风格时对其进行更新。

代码集成请参考相应框架的文档，下文的提取和翻译步骤则使用 CLI 完成。通过 MCP 连接，智能体可以访问实时项目及其上下文；但应用本身仍需完成 SDK 初始化设置、准备已翻译内容并进行验证。

## 添加包含验收标准的功能说明

将这份功能说明添加到官方初始化设置提示词中。请将其中的功能和区域设置替换为你自己的需求；以下示例使用英语、西班牙语和法语。

```text
将此应用中的项目列表功能国际化。
以英语作为源语言，以西班牙语和法语作为目标语言。
范围包括标题、所有者名称、项目数量、搜索输入框、可见标签、
占位符和语言选择器。使用随应用本地打包的译文，
并保留现有的路由和提供者。在权限允许时，通过已连接的 GT MCP 服务器
读取项目设置和已分配的术语。如有
连接或权限方面的缺失，请予以报告。不要更改此任务范围之外的共享上下文。
验证数量为 0、1 和 2 的情况、包含标点符号的名称、输入框标签和
占位符、语言切换、重新加载后的持久化，以及生产环境构建。
如果此应用使用 SSR，请检查服务器端渲染的内容。报告实际执行的命令
及其结果、翻译审核状态以及所有未经测试的内容。源模板
不等于已完成的翻译。仅修改此功能及其初始化设置。
不要部署或合并。
```

请将项目规则写入你的智能体会读取的指令机制中。Cursor 的文档介绍了[项目规则和 AGENTS.md](https://cursor.com/docs/rules)；Claude Code 的文档介绍了 [CLAUDE.md 及其他项目指令](https://code.claude.com/docs/en/memory)。将选定的库、源区域设置、翻译命令以及必须执行的检查添加到现有指令中。不要同时维护多份可能逐渐不一致、相互冲突的副本。

## 查看典型实现

对于纯浏览器端的 React 应用，[React SPA 快速入门](/docs/react/react-spa-quickstart)会在渲染前配置 `gt-react`。本示例假定你已完成该初始化设置，且本地输出位于 `src/_gt/[locale].json`。示例使用 `gt-react@11.4.12` 和 `gt@2.26.5` CLI。

下面的组件涵盖静态文案、动态值、复数形式和输入文本。渲染该组件时，请传入应用中的项目数量和所有者名称。

```tsx title="src/ProjectSummary.tsx"
import { Num, Plural, T, Var, useGT } from 'gt-react';

export default function ProjectSummary({
  count,
  ownerName,
}: {
  count: number;
  ownerName: string;
}) {
  const gt = useGT();

  return (
    <section>
      <T>
        <h1>Projects for <Var>{ownerName}</Var></h1>
        <p>
          <Plural
            n={count}
            one={<>You have <Num>{count}</Num> project.</>}
            other={<>You have <Num>{count}</Num> projects.</>}
          />
        </p>
      </T>
      <label>
        <T>Search projects</T>
        <input type='search' placeholder={gt('Search projects')} />
      </label>
    </section>
  );
}
```

[`<Var>`](/docs/react/reference/components/var) 会在翻译周围消息的同时保留所有者的名称，且其值不会发送到翻译 API。[`<Plural>`](/docs/react/reference/components/plural) 根据区域设置的规则选择分支，[`<Num>`](/docs/react/reference/components/num) 则负责格式化计数。[`useGT`](/docs/react/reference/hooks/use-gt) 直接返回翻译函数。可见标签包裹了输入框，因此该控件既有标签，也有已翻译的占位符。

`one` 和 `other` 分支描述的是英文源内容。目标语言的译文必须体现该语言自身的复数形式；不要以为测试过英文的单复数两种形式就能覆盖所有语言。请参阅 [React 复数处理指南](/kb/how-to-handle-plurals-in-react)。

在 React SPA 中，按文档进行的 [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) 初始化设置会先于应用加载译文。其提供的 [`LocaleSelector`](/docs/react/reference/components/locale-selector) 会将所选语言保存到 cookie 中，并重新加载页面。服务器端渲染框架的初始化设置要求有所不同，请参阅相应框架的快速入门。

## 先生成译文，再评估结果

进行本地试用时，请在添加该组件后，在已配置的应用目录中运行以下命令：

```bash
npx gt generate
```

[`gt generate`](/docs/cli/reference/commands/generate) 只会创建源模板，不会调用翻译服务。请在西班牙语和法语文件中填入译文，同时保留生成的键、变量标记和 JSX 结构。有 `es.json` 文件，并不代表其中已经是西班牙语内容。

如需由服务生成译文，请先完成 [CLI 身份验证与项目初始化设置](/docs/cli/quickstart)，再使用 [`gt translate`](/docs/cli/reference/commands/translate)。身份验证可通过 CLI 登录或 API 密钥完成，项目 ID 则需单独配置；仅登录并不会选定项目。对于无人值守的 CI，请通过 CI 服务商的密钥设置提供 `GT_API_KEY`，并为其授予翻译工作流所需的权限。详见[凭据配置指南](/docs/cli/guides/configuring#credentials)，并确保工具类密钥不会出现在浏览器代码中。使用该服务将计入用量。

General Translation 会结合 JSX 结构以及你提供的显式上下文来翻译已标记的 JSX。对于含义有歧义的文案，请添加 [`context` 属性](/docs/react/reference/components/t#context)，并应用项目共享的[词汇表术语和自定义提示词](/docs/platform/dashboard/guides/defining-context-for-translations)，以规范产品术语和语气。这样，翻译生成所遵循的产品规则，就与编程智能体通过 MCP 读取的规则保持一致。

使用[本地随应用打包的译文](/docs/react/guides/storing-translations)时，请在生产环境构建之前准备好区域设置文件。手动维护的文件应纳入版本控制或翻译流水线中保存。如果手动编辑的译文只有这一份，切勿把它当作可随意丢弃的生成产物而忽略。

## 先验证功能，再逐步扩展

运行 [`gt validate`](/docs/cli/reference/commands/validate)，在发起 API 请求前捕获受支持的内联翻译错误，然后让智能体逐项报告下列检查的实际结果。

| 检查项                     | 预期结果                   |
| ----------------------- | ---------------------- |
| 先选择西班牙语，再选择法语           | 标题、计数消息、标签和占位符均显示为所选语言 |
| 选择语言后重新加载               | 所选语言按应用的策略保留           |
| 分别测试计数 0、1 和 2          | 每种语言都使用各自的复数规则，数字显示正确  |
| 使用 O&#39;Connor 这类所有者名称 | 该名称在所有语言中均保持完整         |
| 检查输入框的无障碍名称             | 与翻译后的可见标签一致            |
| 运行生产环境构建并预览             | 使用最终发布的文件时，该功能同样正常运行   |

在本示例中，[法语的零和英语的零属于不同的复数类别](https://cldr.unicode.org/index/cldr-spec/plural-rules)。请检查渲染出的句子是否使用了正确的形式，且计数未丢失。

确认该模式可行后，每次只扩展一个路由或功能。审阅者可以在[仪表板翻译编辑器](/docs/platform/dashboard/guides/reviewing-translations)中编辑译文。邀请译者、项目经理和本地审阅者需要 Starter 或 Enterprise 方案，两者均包含[不限数量的用户](https://generaltranslation.com/pricing)。Enterprise 方案还提供翻译审批功能。如果你的团队会编辑生成的本地文件，可选择启用 [`gt save-local`](/docs/cli/reference/commands/save-local)，上传这些更改以便日后复用。审阅工作流详见[审阅 AI 翻译](/kb/review-translations)。

## 智能体会话结束后，让本地化持续运行

将 [`gt translate` 放在生产环境构建之前](/docs/cli/guides/generating-translations)，即可在源文案变更时自动更新译文。增量工作流会复用匹配的译文，无需每次运行都重新生成全部消息。

如果希望持续推进本地化工作，又不想亲自操控编码助手，可以使用 General Translation 的托管智能体 [Locadex](/docs/platform/locadex/guides/configuring-automations)：它能够对新增 UI 进行国际化、生成译文，并同步新增或移除的区域设置。你可以配置拉取请求、推送或手动触发器，变更会以拉取请求的形式提交。[Auto-merge](/docs/platform/locadex/guides/auto-merging-prs) 为可选功能。你可以先用编码助手完成集成搭建，再由 Locadex 在后续发布中持续维护。Locadex 需要 Starter 或 Enterprise 方案，其运行按[用量](https://generaltranslation.com/pricing/usage)计费。初始化设置请参阅[自动化参考](/docs/platform/locadex/reference/automations)，你也可以使用自己的流水线[在 CI 中运行翻译](/kb/translations-in-ci)。

## 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 负责生成、审阅和持续更新。本指南还演示了如何显式配置本地文件。
- [不使用翻译文件能实现 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 还能通过拉取请求让译文保持最新。
- [如何在 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 便会生成每种目标语言所需的形式。
- [Locadex 智能体能做什么？](https://generaltranslation.com/zh/kb/what-is-locadex.mdx): Locadex 是 General Translation 推出的 AI 智能体，可在你的 GitHub 代码仓库中对代码进行国际化处理并翻译内容。它的自动化流程会在创建拉取请求、推送提交或你手动启动时运行，所有更改都以拉取请求的形式交付。

## Previous and next questions

- Previous question: [如何为 Next.js App Router 应用添加 i18n？](https://generaltranslation.com/zh/kb/add-i18n-to-nextjs.mdx)
- Next question: [如何在 Sanity 中翻译内容？](https://generaltranslation.com/zh/kb/translate-sanity-content.mdx)

## Sitemap

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