# General Translation Overview: 使用代码智能体
URL: https://generaltranslation.com/zh/docs/overview/for-coding-agents.mdx
---
title: 使用代码智能体
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。使用代码块右上角的复制按钮。

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

本指南面向将 [General Translation](https://generaltranslation.com) 集成到项目中的 AI 编程智能体。General Translation 是一款全栈本地化产品：开源 i18n 库加上 CLI，可将应用及其内容翻译成任意语言。在国际化代码或接入翻译功能时，请遵循以下规则。

## 选择合适的包

根据技术栈选择对应的包：

- **Next.js（App Router 或 Pages Router）** → `gt-next`
- **React（SPA，如 Vite）** → `gt-react`
- **Node.js 服务端** → `gt-node`
- **任意 JavaScript 运行时或需要底层控制** → `generaltranslation`（Core 库）
- **翻译内容文件（JSON、MDX、YAML 等）或在 CI 中运行翻译** → `gt` CLI

以上所有工具均免费且开源。这些库无论是否拥有 General Translation 账号均可使用；API Key 可解锁开发环境中的按需翻译功能以及托管翻译 API。

## 初始化配置

推荐使用向导。在项目根目录运行：

```bash
npx gt init
```

该命令会安装所需的库和 `gt` CLI，完成框架接入（对于 Next.js，会添加 `withGTConfig` 和 `GTProvider`），创建 `gt.config.json`，并生成 API 凭据。

如需手动配置，请自行安装相关包：

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

然后在项目根目录创建 `gt.config.json`——这是区域设置的唯一配置来源：

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

- `defaultLocale` — 源内容所使用的语言。
- `locales` — 需要翻译的目标语言列表。
- `files.gt.output` — CLI 写入翻译文件的路径（`[locale]` 会按语言替换）。请将该目录添加到 `.gitignore`，因为这些文件是自动生成的。

将 API 凭据设置为环境变量（Next.js 使用 `.env.local`，其他情况使用 `.env`）：

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

切勿将 `GT_API_KEY` 提交到代码库、暴露给浏览器，或为其添加 `NEXT_PUBLIC_` 前缀。

## 核心用法

将面向用户的 JSX 包裹在 `<T>` 中。直接编写源文本内容，无需翻译键：

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

// <T> 内的所有内容作为一个整体进行翻译
<T>
  <h1>Welcome to my app</h1>
</T>;
```

对于独立字符串（占位符、`aria-label`、`alt`、按钮标签等），请使用 `useGT()`。`useGT()` 直接返回翻译函数：

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

const gt = useGT(); // ✅ 正确
// const { gt } = useGT(); // ❌ 错误 — useGT 返回的是函数本身，而非对象

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

在异步 App Router 组件中，请改用 `getGT`。`gt-next/server` 不支持 Pages Router：

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

const gt = await getGT();
```

将动态或私密值（姓名、邮箱、ID 等）包裹在 `<Var>` 中，使其不被翻译且不会发送至 API。对于需要重新格式化但不需要翻译的值，请使用 `<Currency>`、`<DateTime>` 和 `<Num>`：

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

// 生成一条翻译，保持姓名不变
<T>
  Hello, <Var>{name}</Var>!
</T>;
```

对于 Node.js 服务端，初始化一次后按请求解析翻译：

```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 中**构建生产版本之前**运行。 |
| `npx gt generate` | 创建翻译文件模板以供手动翻译（无需 API Key）。 |

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

## 规范——应做与不应做

应做：

- 编写代码时，将每一处新的面向用户文本包裹在 `<T>` 中（独立字符串使用 `useGT()`/`getGT()`）。
- 在提交代码或构建生产版本之前运行 `npx gt translate`，确保新内容已被翻译。
- 仅在 `gt.config.json` 中维护区域设置列表。
- 将动态和私密值包裹在 `<Var>` 中，并在字符串含义不明确时添加 `context`。

不应做：

- 在源代码中硬编码已翻译的字符串，或添加按语言区分的 `if`/`switch` 分支——应翻译源文本本身。
- 手动编辑自动生成的翻译文件（CLI 会覆盖它们）。
- 提交 `GT_API_KEY` 或将其暴露给客户端。
- 在 `gt.config.json` 之外重复配置区域设置。

## 相关链接

- [`llms.txt`](/llms.txt) — 简短的机器可读文档索引。
- [`sitemap.md`](/sitemap.md) — 所有文档页面的目录。
- Quickstart：[React](/docs/react/react-quickstart)、[Node](/docs/node/quickstart)、[Core 库](/docs/platform/core/quickstart) 以及 [CLI](/docs/cli/quickstart)。
- [核心概念](/docs/overview/key-concepts) — 区域设置、上下文，以及静态内容与动态内容的区别。
````

## 让智能体使用文档 [#point-agents]

让你的智能体直接访问文档，这样它给出的回答才能保持准确。General Translation 在站点根目录提供了几个机器可读的入口文件：

* [`llms.txt`](/llms.txt) — 一个简短的、采用 [llmstxt.org](https://llmstxt.org/) 风格的文档索引。
* [`sitemap.md`](/sitemap.md) — 按导航顺序链接所有页面的网站地图。

每个文档页面也都提供 **原始 Markdown**：只需在任意页面 URL 后追加 `.md` (例如 `/docs/cli/quickstart.md`) ，即可获取干净的源内容，而不用解析渲染后的 HTML。

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

## MCP 服务器 [#mcp]

General Translation 提供了一个 [Model Context Protocol](https://modelcontextprotocol.io) (MCP) 服务器，让智能体能够直接查询文档。它有两种形式：

* **本地 (stdio)&#x20;**&#x20;— 已发布的 [`@generaltranslation/mcp`](https://www.npmjs.com/package/@generaltranslation/mcp) npm 包，可通过 `npx` 在你的机器上运行。最适合保持持久连接的工具，例如 Cursor 和 Claude Code。
* **远程 (HTTP/SSE)&#x20;**&#x20;— 托管在 `https://mcp.gtx.dev` 的端点。仅当你的工具不支持可流式 HTTP 时，才使用 SSE 端点。

使用你的工具所支持的传输方式来配置连接。各种工具的配置结构完全相同——将其添加到工具的 MCP 配置文件中 (例如 `.mcp.json`) ：

<Tabs items={['Local', 'Streamable HTTP', 'SSE']}>
  <Tab value="Local">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "command": "npx",
          "args": ["-y", "@generaltranslation/mcp@latest"]
        }
      }
    }
    ```
  </Tab>

  <Tab value="Streamable HTTP">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "type": "streamable-http",
          "url": "https://mcp.gtx.dev"
        }
      }
    }
    ```
  </Tab>

  <Tab value="SSE">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "type": "sse",
          "url": "https://mcp.gtx.dev/sse"
        }
      }
    }
    ```
  </Tab>
</Tabs>

连接后，让你的智能体使用 `generaltranslation` MCP 服务器。*示例：“使用 generaltranslation MCP 服务器解释如何使用 [`<T>`](/docs/react/reference/components/t) 组件。”*

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

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

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

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

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

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