# 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

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`
- **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'] });
// wrap handlers in withGT(locale, ...); then `const gt = await getGT()` inside them
```

Keep all locale configuration in `gt.config.json` — do not scatter locale lists across the codebase.

## Commands

| Command | When to run |
| --- | --- |
| `npx gt init` | Once, to set up a project (installs deps, configures the framework, creates `gt.config.json`, generates credentials). |
| `npx gt configure` | To create or update `gt.config.json` (locales and files) without the full wizard. |
| `npx gt auth` | To generate or refresh API credentials. |
| `npx gt translate` | To translate the project via the General Translation API. Run in CI **before** building for production. |
| `npx gt generate` | To create translation file templates to translate manually (no API key needed). |

Add translation to the production build so translations stay current, for example: `"build": "npx gt translate && next build"`.

## Rules — do and don't

Do:

- Wrap every new piece of user-facing copy in `<T>` (or `useGT()`/`getGT()` for standalone strings) as you write it.
- Run `npx gt translate` before committing or building for production so new copy is translated.
- Keep the locale list in `gt.config.json` only.
- Wrap dynamic and private values in `<Var>`, and add `context` when a string is ambiguous.

Don't:

- Hardcode already-translated strings in the source, or add per-language `if`/`switch` branches — translate the source copy instead.
- Hand-edit generated translation files (the CLI overwrites them).
- Commit `GT_API_KEY` or expose it to the client.
- Duplicate the locale configuration outside `gt.config.json`.

## Links

- [`llms.txt`](/llms.txt) — 简短的机器可读文档索引。
- [`llms-full.txt`](/llms-full.txt) — 适用于可加载更大上下文的工具的完整文档内容。
- [`sitemap.xml`](/sitemap.xml) — 所有已发布页面的目录。
- 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 会在文档主机的站点根目录以及 `/docs` 下发布几个机器可读的入口文件：

* [`llms.txt`](/llms.txt) — 一个简短的、采用 [llmstxt.org](https://llmstxt.org/) 风格的文档索引。
* [`llms-full.txt`](/llms-full.txt) — 将完整文档内容汇总到单个文件中，不包括生成的 OpenAPI 参考。
* [`sitemap.xml`](/sitemap.xml) — 以机器可读格式列出每个已发布页面的网站地图。

文档主机也会在 `/docs/llms.txt` 和 `/docs/llms-full.txt` 提供这些文件。每个文档页面也都提供 **原始 Markdown**：只需在任意页面 URL 后追加 `.md` 或 `.mdx` (例如 `/docs/cli/quickstart.mdx`) ，即可获取干净的源内容，而不用解析渲染后的 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>`](/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) (词汇表和 Directives) 、区域设置配置 (`defaultLocale` 和 `locales`) ，以及确认动态值或私密值已用 [`<Var>`](/docs/react/reference/components/var) 包裹。
* **绝不要让智能体做：**手动编辑生成的翻译文件，或绕过 CLI 去硬编码已翻译好的字符串，而不是翻译源文案。