# General Translation Overview: 使用代码智能体
URL: https://generaltranslation.com/zh/docs/overview/for-coding-agents.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 如何让 AI 代码智能体和 LLMs 通过机器可读文档、MCP 服务器以及我们的即插即用智能体指南来使用 General Translation。

General Translation 专为与 AI 代码智能体和 LLMs 配合使用而构建。相关库均为开源，配置方式清晰可预期，文档也以机器可读格式发布。像 Cursor、Claude Code 或 Copilot 这样的智能体，可以凭借准确且最新的上下文，为你添加并运行 General Translation。

*如果你需要能够自行发起 pull request 的全自动本地化，请使用我们的专用智能体 [Locadex](/docs/platform/locadex/quickstart)，而不是自己驱动智能体。*

## 即插即用智能体指南 [#agent-guide]

只需粘贴一次，就能为你的智能体提供所需的一切。将下方指南复制到项目根目录中的 `AGENTS.md` (或 `CLAUDE.md`、Cursor 规则或你的工具说明文件) 里，你的智能体就能正确添加并运行 General Translation。使用代码块右上角的复制按钮，或直接从 [`/AGENTS.md`](/AGENTS.md) 获取同一份指南。

````markdown title="AGENTS.md"
# General Translation — agent guide

Instructions for AI coding agents adding [General Translation](https://generaltranslation.com) to a project. General Translation is a full-stack localization product: open-source i18n libraries plus a CLI that translate an app and its content into any language. Follow these rules when internationalizing code or wiring up translations.

## What to use

Pick the package that matches the stack:

- **Next.js (App Router or Pages Router)** → `gt-next`
- **React (SPA, e.g. Vite)** → `gt-react`
- **Vue 3** → `gt-vue`
- **Node.js server** → `gt-node`
- **Any JavaScript runtime, or lower-level control** → `generaltranslation` (the Core library)
- **Translating content files (JSON, MDX, YAML, and more) or running translation in CI** → the `gt` CLI

All of these are free and open-source. The libraries work with or without a General Translation account; an API key unlocks on-demand translation in development and the hosted translation API.

## Setup

Prefer the wizard. From the project root, run:

```bash
npx gt init
```

It installs the right library and the `gt` CLI, wires up the framework (for Next.js, adds `withGTConfig` and `GTProvider`), creates `gt.config.json`, and generates API credentials.

For manual setup, install the packages yourself:

```bash
npm install gt-next   # or gt-react / gt-node / generaltranslation
npm install -D gt
```

Then create `gt.config.json` in the project root — this is the single source of truth for locales:

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

- `defaultLocale` — the language the source is written in.
- `locales` — the languages to translate into.
- `files.gt.output` — where the CLI writes translation files (`[locale]` is replaced per language). Add this directory to `.gitignore`; the files are generated.

Set API credentials as environment variables (in `.env.local` for Next.js, `.env` otherwise):

```bash
GT_API_KEY="gtx-dev-..."   # gtx-dev- in development, gtx-api- in production/CI
GT_PROJECT_ID="..."
```

Never commit `GT_API_KEY`, expose it to the browser, or prefix it with `NEXT_PUBLIC_`.

## Core usage

Wrap user-facing JSX in `<T>`. Write source copy directly — no translation keys needed:

```tsx
import { T } from 'gt-next'; // or 'gt-react'

// Everything inside <T> is translated as a unit
<T>
  <h1>Welcome to my app</h1>
</T>;
```

Use `useGT()` for standalone strings (placeholders, `aria-label`, `alt`, button labels). `useGT()` returns the translation function directly:

```tsx
import { useGT } from 'gt-next';

const gt = useGT(); // ✅ correct
// const { gt } = useGT(); // ❌ wrong — useGT returns the function, not an object

<input placeholder={gt('Search products')} />;
```

In async App Router components, use `getGT` instead. `gt-next/server` does not work with the Pages Router:

```tsx
import { getGT } from 'gt-next/server';

const gt = await getGT();
```

Wrap dynamic or private values (names, emails, IDs) in `<Var>` so they are not translated and never sent to the API. Use `<Currency>`, `<DateTime>`, and `<Num>` for values that should be reformatted but not translated:

```tsx
import { T, Var } from 'gt-next';

// Generates one translation, keeps the name unchanged
<T>
  Hello, <Var>{name}</Var>!
</T>;
```

For Node.js servers, initialize once and resolve translations per request:

```js
import { initializeGT, withGT, getGT } from 'gt-node';

initializeGT({ defaultLocale: 'en', locales: ['en', 'es', 'fr'] });
// 用 withGT(locale, ...) 包裹处理程序；然后在其中使用 `const gt = await getGT()`
```

将所有区域设置配置保留在 `gt.config.json` 中 —— 不要把区域设置列表分散在整个代码库中。

## 命令

| 命令                          | 何时运行                                                                                                                                                         |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npx gt init`                    | 运行一次，用于设置项目（安装依赖、配置框架、创建 `gt.config.json`、生成凭据）。                                               |
| `npx gt configure`               | 无需完整向导即可创建或更新 `gt.config.json`（区域设置和文件）。                                                                                   |
| `npx gt auth`                    | 生成或刷新 API 凭据。                                                                                                                             |
| `npx gt translate`               | 通过 General Translation API 翻译项目。在 CI 中于生产构建**之前**运行；仅当需要先同步本地修改时才添加 `--save-local`。 |
| `npx gt generate`                | 创建用于手动翻译的翻译文件模板（无需 API 密钥）。                                                                                     |
| `npx gt api --spec`              | 查看随所安装 CLI 一起提供的 OpenAPI 契约。                                                                                     |
| `npx gt api <endpoint>`          | 从脚本或终端发起经过身份验证的原始 API 请求。                                                                                 |
| `npx gt project create --org-id <orgId> --name <name> --default-locale <locale>` | 使用组织密钥创建项目。 |
| `npx gt project status <job-id>` | 查看翻译作业或项目上下文生成作业。                                                                                         |

将翻译加入生产构建，以保持翻译为最新，例如：`"build": "npx gt translate && next build"`。

## 规则 —— 该做与不该做

该做：

- 在编写时，将每一段新的面向用户的文案包裹在 `<T>` 中（独立字符串则使用 `useGT()`/`getGT()`）。
- 在提交或进行生产构建之前运行 `npx gt translate`，以便翻译新文案。
- 仅在 `gt.config.json` 中维护区域设置列表。
- 将动态值和私密值包裹在 `<Var>` 中，并在字符串含义不明确时添加 `context`。
- 在有意编辑生成的翻译文件之后，请先运行 `npx gt save-local` 再重新下载翻译，或在下一次翻译运行时传入 `--save-local`。

不该做：

- 在源码中硬编码已翻译的字符串，或添加按语言的 `if`/`switch` 分支 —— 应改为翻译源文案。
- 编辑生成的翻译文件却不同步这些更改；后续下载可能会覆盖未保存的编辑。
- 提交 `GT_API_KEY` 或将其暴露给客户端。
- 在 `gt.config.json` 之外重复配置区域设置。

## 链接

- [`llms.txt`](/llms.txt) —— 精选的机器可读文档入口。
- [`llms-index.txt`](/llms-index.txt) —— 涵盖所有文档页面的完整索引。
- [`llms-full.txt`](/llms-full.txt) —— 面向可加载更大上下文的工具的完整文档内容。
- [React 索引](/docs/react/llms.txt)、[CLI 索引](/docs/cli/llms.txt) 和 [OpenAPI 索引](/docs/platform/openapi/llms.txt) —— 面向常见任务的聚焦入口。
- [`AGENTS.md`](/AGENTS.md) —— 本即插即用指南的原始 Markdown 版本。
- [`openapi.yaml`](/openapi.yaml) —— General Translation API 的权威规范。
- [`sitemap.md`](/sitemap.md) —— 所有文档页面和博客文章的 Markdown 索引。
- [`sitemap.xml`](/sitemap.xml) —— 面向所有已发布页面的标准站点地图。
- 快速上手：[React](/docs/react/react-quickstart)、[Vue](/docs/vue/quickstart)、[Node](/docs/node/quickstart)、[核心库](/docs/platform/core/quickstart)，以及 [CLI](/docs/cli/quickstart)。
- [关键概念](/docs/overview/key-concepts) —— 区域设置、上下文，以及静态与动态内容。
- CLI 参考：[`gt api`](/docs/cli/reference/commands/api)、[`gt project create`](/docs/cli/reference/commands/project-create) 和 [`gt project status`](/docs/cli/reference/commands/project-status)。
````

## 让智能体访问文档 [#point-agents]

让智能体直接访问文档，以保证其回答的准确性。General Translation 在文档站点根路径以及 `/docs` 路径下提供了多个机器可读的入口文件：

* [`llms.txt`](/llms.txt) — 经过精选整理的 [llmstxt.org](https://llmstxt.org/) 风格入口文件，包含主要的 Quickstart 和专项索引。
* [`llms-index.txt`](/llms-index.txt) — 涵盖所有已发布文档页面的完整链接索引。
* [`llms-full.txt`](/llms-full.txt) — 汇总于单个文件中的完整文档内容，不包含自动生成的 OpenAPI 参考。
* [`AGENTS.md`](/AGENTS.md) — 上述即插即用指南的 raw Markdown 形式。
* [`sitemap.md`](/sitemap.md) — 涵盖所有文档页面和博客文章的 Markdown 索引。
* [`sitemap.xml`](/sitemap.xml) — 涵盖所有已发布页面的标准 XML sitemap。

如果智能体已经明确需要产品的哪一部分内容，可使用范围更小的索引：

* [Overview](/docs/overview/llms.txt)
* [Platform](/docs/platform/llms.txt)，并提供针对 [仪表板](/docs/platform/dashboard/llms.txt)、[Locadex](/docs/platform/locadex/llms.txt)、[Core](/docs/platform/core/llms.txt) 和 [OpenAPI](/docs/platform/openapi/llms.txt) 的专项索引
* [CLI](/docs/cli/llms.txt)
* [React](/docs/react/llms.txt)
* [Vue](/docs/vue/llms.txt)
* [Node.js](/docs/node/llms.txt)
* [Python](/docs/python/llms.txt)
* [Integrations](/docs/integrations/llms.txt)

涉及 API 的工作，请使用 [OpenAPI 操作合集](/docs/platform/openapi/llms-full.txt)或权威的 [`openapi.yaml`](/openapi.yaml) 规范文件，而不要去抓取交互式 endpoint 页面。

文档站点同样在 `/docs` 下提供这些根文件，包括 `/docs/llms.txt`、`/docs/llms-index.txt` 和 `/docs/llms-full.txt`。每个文档页面都可以获取其 **raw Markdown** 形式：在任意页面 URL 后追加 `.md` 或 `.mdx`，即可直接获取干净的源文件，无需解析渲染后的 HTML。自动生成的索引和发现类元数据使用 `.mdx`，例如 `/docs/cli/quickstart.mdx`。

要将文档添加为上下文，可将文档 URL 或 `llms.txt` 链接粘贴到智能体的上下文中，或在支持文档索引的工具中将文档添加为 source。

## MCP 服务器 [#mcp]

当你的智能体需要通过本地 [Model Context Protocol](https://modelcontextprotocol.io) (MCP) 连接、基于标准输入输出获取文档时，请使用已发布的 [`@generaltranslation/mcp`](https://www.npmjs.com/package/@generaltranslation/mcp) 包：

```json title=".mcp.json"
{
  "mcpServers": {
    "generaltranslation-docs": {
      "command": "npx",
      "args": ["-y", "@generaltranslation/mcp@latest"]
    }
  }
}
```

该 package 提供了列出和获取文档的工具。若只需更简单的文档访问方式，可直接让智能体指向[机器可读文档](#point-agents)。

若需获取实时项目信息，请使用位于 `https://api.gtx.dev/mcp` 的托管 MCP 服务器。它采用可流式 HTTP。

该托管服务器还提供 [Google Drive MCP 工具](/docs/integrations/google-drive/reference/mcp-tools)，可用于查找已连接的项目、翻译 Google Docs 和 Google Slides，以及轮询译文副本的进度。

将该连接添加到所用工具的 MCP 配置文件 (例如 `.mcp.json`) 中。传输方式名称和配置字段可能因客户端而异：

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

### 通过远程 API 进行身份验证

可通过 MCP 客户端的 OAuth 登录流程进行连接，或使用其密钥请求头设置配置 `Authorization: Bearer <api-key>`。API 密钥连接支持生产环境项目密钥 (`gtx-api-`)、开发环境项目密钥 (`gtx-dev-`) 和组织密钥 (`gtx-org-`)。是否允许使用开发密钥由各个工具自行决定；运行时翻译和 [Google Drive MCP 工具](/docs/integrations/google-drive/reference/mcp-tools)支持开发密钥，而其他工具可能会拒绝。

该服务器会公布其受保护资源元数据和授权服务器元数据。支持 OAuth 的客户端可动态注册，使用带 PKCE (Proof Key for Code Exchange) 的授权码流程，并打开仪表板的授权同意页面。请求 `openid` 和 `profile` 以获取身份声明；当客户端需要刷新令牌时，请求 `offline_access`。

使用 `list_projects` 查找项目 ID，然后将其作为 `projectId` 传给项目工具。生产环境项目密钥可以省略 `projectId`，此时将使用其自身所属的项目。

连接完成后，让你的智能体使用 `generaltranslation` MCP 服务器。可以试试：“列出我的项目，并显示其中一个项目的区域设置。”

## 各编辑器专属提示 [#editor-tips]

大多数 setup 在各个智能体之间都相同；只有少数几处说明会有所不同。

* **Cursor** — 注册 MCP 服务器，然后让它“使用 `generaltranslation` 工具”。将文档添加为 source，或在提示词中引用 `/llms.txt`。
* **Claude Code** — 会自动读取根目录下的 `CLAUDE.md`，因此请将[智能体指南](#agent-guide)复制到项目的 `CLAUDE.md` 中。注册 MCP 服务器，并让它“使用 `generaltranslation` MCP 服务器”。
* **Copilot** — 将整个 repo 的说明放在你的指令文件中 (例如 `.github/copilot-instructions.md`) ，并在其中引用文档 `/llms.txt`。

## 最佳实践 [#best-practices]

智能体很适合处理机械性的 i18n 工作，但翻译质量和配置仍然仍需人工把关。建议按以下方式分工：

* **交给智能体：**用 [`<T>`](/docs/react/reference/components/t) 包裹面向用户的文案，为独立的字符串添加 [`useGT()`](/docs/react/reference/hooks/use-gt)，搭建 `gt.config.json` 的基础结构，以及运行 [`npx gt init`](/docs/cli/reference/commands/init)。
* **人工核查：**智能体编写的[翻译上下文](/docs/overview/key-concepts#context) (词汇表和自定义提示词) 、区域设置配置 (`defaultLocale` 和 `locales`) ，以及确认动态值或私密值已用 [`<Var>`](/docs/react/reference/components/var) 包裹。
* **绝不要让智能体做：**编辑生成的翻译文件却不同步这些改动，或绕过 CLI 去硬编码已翻译好的字符串，而不是翻译源文案。

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.