# 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)，而不是自己驱动智能体。* ## 启动提示词 [#start-prompt] 下面的提示词会启动一个智能体会话，将 General Translation 添加到你的项目中：智能体会阅读文档入口文件，通过 [`gt login`](/docs/cli/reference/commands/login) 登录，选择一个项目，完成首个翻译并加以验证。智能体正是通过 [`gt login`](/docs/cli/reference/commands/login) 与 General Translation 平台协作的，因此提示词以它开头，而不是向你索要 API Key。[generaltranslation.com](https://generaltranslation.com) 上的 **Setup for Agents** 按钮复制的正是这段文本，同样的内容也以原始文本形式发布在 [`/agent-prompt.md`](/agent-prompt.md)。提示词中给出的 [`init`](/docs/cli/reference/commands/init) 命令已基于 `gt` 2.24.0 在全新的 `create-next-app` 项目上验证通过：它无需任何交互，会安装 `gt-next`，将 [`GTProvider`](/docs/react/reference/components/gt-provider) 添加到根布局、将 `withGTConfig` 添加到 `next.config.ts`，创建 `loadTranslations.js` 和 `gt.config.json`，最后以成功事件结束。 ````markdown title="agent-prompt.md" # Get started with General Translation I landed on https://generaltranslation.com and clicked "Setup for Agents". Help me add General Translation to my app, website, or content, and get a real translation working. Inspect the project you have access to, choose the appropriate integration with me, and implement it. Continue through setup, translation, and verification rather than stopping at a plan. ## About General Translation General Translation (GT) combines open-source internationalization libraries, a translation CLI, and a hosted translation platform. Source content stays in your code or content files. The libraries render translations and format locale-sensitive values; the platform generates and manages translations. Locadex is an optional hosted agent that connects to GitHub and maintains localization through pull requests. - Website: https://generaltranslation.com - Dashboard: https://dash.generaltranslation.com - Open-source libraries and CLI: https://github.com/generaltranslation/gt - Documentation entry point: https://generaltranslation.com/llms.txt - Complete documentation index: https://generaltranslation.com/llms-index.txt - API specification: https://generaltranslation.com/openapi.yaml Fetch the documentation entry point first, then the quickstart and references relevant to this project. Documentation pages are available as raw Markdown by appending `.mdx` to the page URL. Use the complete index when you need a page that is not in the curated index. Read current docs and installed command help instead of guessing APIs, flags, or framework setup. `gt auth` is not a command in current releases; use `gt login`. `gt generate` writes source templates without calling the API and is registered when the CLI detects `gt-next`, `gt-react`, `gt-react-native`, `gt-tanstack-start`, `gt-node`, `gt-vue`, `gt-flask`, or `gt-fastapi`. Use `gt translate` for hosted translation. ## Work with me Read this entire prompt before acting. Respect the repository's instructions, package manager, architecture, design system, and existing changes. First inspect the repository for the framework, router, app directory, existing i18n library, GT configuration, source language, and build scripts. In a monorepo, identify the specific app or content directory; do not run setup at the workspace root. Do not ask me things you can determine from the code. If the intended project is unclear, ask one question: "What would you like to translate?" Offer concrete choices: this app or website, documentation or content files, a backend service, a connected content platform, or a small new demo. Include "Not sure, help me decide." Prefer your interactive question tool when available. If no repository is open, help me open one or choose a small demo before scaffolding anything. Ask for missing decisions one at a time: source language, target languages, and the first page or workflow to translate. Preserve existing locale choices; do not assume the source language is English or invent target markets. If I want help choosing, propose one target language for the first working example. Reuse an existing i18n setup where appropriate instead of automatically migrating the entire application. Explain the next meaningful step briefly, then do the work. Ask when a choice affects which organization/project you use, creates an unwanted duplicate, or changes the agreed scope. Once I have chosen the project, languages, and scope, proceed with the setup and translation needed for that outcome. ## Choose the right integration Read the matching quickstart before making framework changes: | Project | Integration | Quickstart | | --- | --- | --- | | Next.js App Router | `gt-next` | https://generaltranslation.com/docs/react/nextjs-quickstart.mdx | | Next.js Pages Router | `gt-next` | https://generaltranslation.com/docs/react/nextjs-pages-router-quickstart.mdx | | React SPA, including Vite | `gt-react` | https://generaltranslation.com/docs/react/react-spa-quickstart.mdx | | Server-rendered React | `gt-react` | https://generaltranslation.com/docs/react/react-quickstart.mdx | | TanStack Start | `gt-tanstack-start` | https://generaltranslation.com/docs/react/tanstack-start-quickstart.mdx | | React Native or Expo | `gt-react-native` | https://generaltranslation.com/docs/react/react-native-quickstart.mdx | | Vue | `gt-vue` | https://generaltranslation.com/docs/vue/quickstart.mdx | | Node.js backend | `gt-node` | https://generaltranslation.com/docs/node/quickstart.mdx | | Python backend | Follow the Python SDK guide | https://generaltranslation.com/docs/python/quickstart.mdx | | JSON, MDX, Markdown, YAML, or existing translation files | `gt` CLI | https://generaltranslation.com/docs/cli/quickstart.mdx | | Lower-level JavaScript translation | `generaltranslation` | https://generaltranslation.com/docs/platform/core/quickstart.mdx | For Mintlify, Sanity, Storyblok, or Google Drive, fetch https://generaltranslation.com/docs/integrations/llms.txt and follow that integration's quickstart. Do not apply a React setup wizard to a content integration. If I want GT to continuously maintain localization through GitHub, read https://generaltranslation.com/docs/platform/locadex/quickstart.mdx and walk me through connecting the repository and creating the appropriate automation. Do not enable auto-merge or change paid plans without my direction. ## Run the CLI without questions The CLI is interactive. When `init` or `configure` is missing an answer, it does not fail: it asks the question in the terminal and waits, with no timeout. In an agent session that wait never ends. So in this session: - Always pass `--no-interactive`. With it, a missing answer is a hard error that lists the flags still needed and changes no file. - Pass a flag for every question before you run the command. `--defaults` accepts the recommended local choices in one flag; you still need `--locales` and, outside local Vite and TanStack Start setups, `--dev-credentials` or `--no-dev-credentials`. Pass explicit `--default-locale`, `--locadex` or `--no-locadex`, `--react-setup` or `--no-react-setup`, and `--file-formats` values only when you want to override the defaults. Local Vite and TanStack Start setups default to `--no-live-translations`; pass `--live-translations` to opt in. Never combine the `--[no-]live-translations` and `--[no-]dev-credentials` flag families. - Pass `--json` to `init` and `configure`. It implies `--no-interactive`, writes one result event to stdout and the rendered screen to stderr. `translate`, `upload`, `api`, `whoami`, `project create` and `api-key create` have no `--json` flag; `translate` prints a progress screen with terminal control sequences, so judge it by its exit code and by the files it writes: `public/_gt/.json`, `gt-lock.json` and `gt.config.json`. - If a command prints a question and stops, you are inside an interactive prompt. End the process and rerun it with `--no-interactive` and the missing flag. Never type an answer into it, and never run a command whose questions you have not answered with flags. - `gt login` is the one step that needs a person: it opens a browser and waits for the sign-in to finish. If no browser can open from this session, run it with `--no-browser`, give me the URL it prints, and wait for me to confirm. `translate`, `upload`, `api`, `whoami`, `project create` and `api-key create` ask nothing when their flags are complete; a missing required flag is an error. ## Sign in with `gt login` Use account login for local CLI authentication. Do not begin by asking me to find and paste an API key. The examples below use `npx gt@latest` to avoid an old local CLI. Use the project's package manager or a current installed `gt` binary when appropriate. Inspect the version and available commands first: ```bash npm view gt version npx gt@latest --help npx gt@latest login --help ``` The CLI has no `--version` flag. `translate` prints "CLI Version: x.y.z" in its banner; `init --json` prints no banner. Read the published version with `npm view gt version` and the installed one from `node_modules/gt/package.json`. This workflow requires a CLI release with `login`, `whoami`, and `api-key create`. If the installed CLI lacks them, check the latest published release. If they are still unavailable, explain the release blocker and continue with local integration work that does not require credentials. Do not silently substitute the older `gt auth` flow, invent flags, or install an unpublished branch into my project. Check for an existing session with `npx gt@latest whoami`. If sign-in is needed, run: ```bash npx gt@latest login ``` Let me complete signup/sign-in and authorization in the browser. Keep the command running while approval is pending. In a remote or headless terminal, use: ```bash npx gt@latest login --no-browser ``` Show me the verification URL and code returned by that command; wait for successful authorization, then verify with `npx gt@latest whoami`. Do not ask for my password or extract OAuth tokens. Login authenticates the CLI; it does not by itself configure the app's project or create its runtime credentials. ## Select a project and create the credentials we need Reuse an existing configured project if it is the intended one. Check for conflicting project IDs in configuration and environment variables without printing secret values. Do not overwrite existing credentials or create another key unnecessarily. 对于受支持的全新应用，请在登录后从应用目录运行初始化向导，并通过选项预先回答所有问题。以下示例适用于在本地设置的 Next.js App Router 应用，翻译存储在代码仓库中，并复用现有项目： ```bash npx gt@latest init --no-interactive --json --defaults \ --default-locale --locales \ --no-locadex --react-setup --file-formats none \ --no-dev-credentials --project-id ``` 此次运行不会提出任何问题：它会安装 gt-next，将 GTProvider 添加到根布局，将 withGTConfig 添加到 next.config.ts，创建 loadTranslations.js 和 gt.config.json，最后输出 `{"type":"result","command":"init","outcome":"success"}`。尽管向导的 completedSteps 列表中显示 "wrapped JSX content"，但它实际上不会用 `` 包裹任何页面文本。请在实现部分的第 4 步中自行对每个页面进行国际化。向导会对其修改的文件运行 biome，可能会将项目的缩进替换为制表符；请恢复项目原有格式。如果 withGTConfig() 已正确添加，可忽略警告 "Unexpected export type in ./next.config.ts"。请对照框架快速入门检查向导所做的更改，因为自动框架设置仍处于实验阶段。 `--defaults` 已涵盖本地存储和翻译目录；仅在需要使用其他值时才传入 `--storage` 和 `--translations-dir`。`--no-dev-credentials --project-id ` 会将 projectId 写入 gt.config.json，且不会创建 env 文件。不需要开发密钥时请使用该选项。如果你已有开发密钥，请自行将 `NEXT_PUBLIC_GT_PROJECT_ID` 和 `NEXT_PUBLIC_GT_DEV_API_KEY` 添加到 `.env.development.local`。`--dev-credentials --project-id ` 则会改为将新的开发密钥和项目 ID 保存到 `.env.local`；`--create-project --org-id --project-name ` 会先创建项目。`--no-react-setup` 适用于已安装 GT 库的应用；在未安装的应用上会失败并提示 "No GT runtime is installed, so select at least one file format to translate"，这是预期行为，因为此时没有可翻译的内容。仅当我们已约定使用托管自动化时才传入 `--locadex`。在进行生产环境构建之前，请将开发密钥（`NEXT_PUBLIC_GT_DEV_API_KEY` 或 `GT_DEV_API_KEY`）从 `.env.local` 移至 `.env.development.local`：`next dev` 会加载该文件，而 `next build` 不会；若存在开发密钥，生产环境构建将拒绝运行。附带本地翻译文件的生产环境构建无需密钥。 如果应用已完成框架设置，请直接按照文档进行配置。使用已认证的 CLI 查找资源： ```bash npx gt@latest api /v2/projects npx gt@latest api /v2/orgs ``` 如果结果有分页，请将 `nextCursor` 作为 `?cursor=` 传入以继续获取。`/v2/orgs` 会列出已登录用户所属的组织（API 密钥只能看到其自身所属的组织）。创建项目还需要在该组织中拥有 `org:projects:create` 权限；如果 `project create` 被拒绝，请询问我使用哪个组织，或在 https://dash.generaltranslation.com 的 Dashboard 中创建项目。请使用实际返回的 ID。目标不明确时，请让我选择。如果我的新账户没有合适的组织，请引导我在 https://dash.generaltranslation.com 创建一个，然后重新查找。 如需在所选组织中创建新项目： ```bash npx gt@latest project create \ --org-id \ --name \ --default-locale ``` 使用返回的项目 ID。`project create` 可能需要组织密钥；请先阅读 `npx gt@latest project create --help`，如不可行则改为在 Dashboard 中创建项目。如需了解端点详情，或缺少对应的高层命令，请在发起请求前查看 `npx gt@latest api --spec` 和最新的 API 文档。 本地 CLI 操作可直接使用登录会话。仅在运行时或无人值守的 CI 工作流需要时，才创建单独的项目密钥。请先查看 `npx gt@latest api-key create --help`。该命令需要指定密钥名称和明确的权限。开发运行时密钥需要 `project:translations:generate`；标准的文件翻译工作流需要 `project:files:read`、`project:files:write` 和 `project:translations:enqueue`。如需其他操作，请对照 API 规范核实；不要默认授予所有权限。 `gt api-key create` 只会向 stdout 输出一次密钥。请将该输出直接写入受保护且已被 Git 忽略的本地配置或指定的密钥存储中，不要在工具输出、聊天或日志中显示。使用 `--project-id` 指定所选项目，用 `--name` 说明其用途，用 `--permission` 指定所需权限。确认操作成功并告知变量名称，但不要显示密钥。 请严格区分以下凭据的用途： - CLI/CI 和服务器端凭据使用 `GT_API_KEY` 和 `GT_PROJECT_ID`。切勿将 `GT_API_KEY` 放入浏览器代码或带公开前缀的变量中。 - 开发运行时翻译使用 `GT_DEV_API_KEY` 和项目 ID。浏览器框架可能需要使用其文档规定的公开前缀，例如 `VITE_GT_DEV_API_KEY`；对于 Next.js，向导会写入 `NEXT_PUBLIC_GT_PROJECT_ID` 和 `NEXT_PUBLIC_GT_DEV_API_KEY`，CLI 也会读取该项目 ID，因此只有 CI 中才需要 `GT_PROJECT_ID`。仅在框架指南要求时才暴露权限范围受限的开发密钥；切勿将开发凭据打包进生产环境的浏览器包中。 - OAuth 凭据应存放在 CLI 的凭据存储中，不要将其复制到应用或 CI 中。 确保本地环境文件已被 Git 忽略。在提交的示例中使用占位符。保留无关的环境设置。本地登录并不会让 CI 或已部署的服务器获得认证。 ## 完成首次完整翻译 1. 安装与检测到的技术栈相匹配的集成。对于现有项目，请只做有针对性的修改，并保持其现有行为不变。 2. 根据约定的源区域设置和目标区域设置、源路径及文件映射，创建或更新 `gt.config.json`。请参阅最新的配置参考文档：https://generaltranslation.com/docs/cli/reference/config.mdx。保留现有设置。翻译输出与加载需一并配置；例如，Vite SPA 导入的翻译文件必须位于其源代码目录树内。不要将某个框架的输出路径或 provider 设置照搬到另一个框架。如果不提交翻译文件，请将翻译输出目录（例如 `public/_gt/`）添加到 `.gitignore`。 3. 遵循对应框架的初始化和路由指南。Next.js App Router 与 Pages Router 的做法不同；React SPA 需在渲染前调用 `initializeGTSPA`；服务器端运行时需要基于请求处理区域设置。实现前请先阅读已安装版本的 API。 4. 对约定的页面或工作流进行国际化，包括可见文本、校验信息、占位符、无障碍标签，以及相关的元数据。在 React 中，用 `` 包裹连贯的静态 JSX。对于 gt-next 中的独立字符串，在客户端组件和同步服务器组件中使用 `useGT()`，在异步服务器组件和 `generateMetadata` 中使用来自 `gt-next/server` 的 `getGT()`。`useGT()` 会直接返回翻译函数。对于 Next.js 元数据，请将静态的 `metadata` 导出替换为 `export async function generateMetadata()`，在其中调用来自 `gt-next/server` 的 `getGT()`，并返回翻译后的标题和描述。动态值请使用 `` 或框架的插值 API；不要让私密值进入翻译源。数字、日期、货币和复数需按区域设置进行处理。对于 Vue、Node 或 Python 技术栈，请使用相应的 API。 5. 在应用现有 UI 的合适位置添加语言切换器。在 gt-next 中，来自 `gt-next` 的 `` 可直接在服务器组件页面中渲染，它自带客户端边界。通过 `useGT()` 为其设置 `aria-label`。保持导航功能正常，并按文档所述验证所选区域设置在页面跳转或重新加载后依然生效。对于后端或纯内容项目，请改为通过其实际的 API 或内容工作流来验证区域设置的选择和翻译输出。 6. 为含义模糊的文案补充有用的上下文。在 `` 上使用 `context` prop，在 `gt()` 和 `getGT()` 调用中使用 `$context` 选项。`` 上的 `$context` 是已弃用的别名，CLI 扫描源代码时会对其发出提示。保留产品名称和术语。不要将密钥或运行时用户数据作为翻译源发送。对于内容文件，请按照格式指南保留 frontmatter、链接、变量和格式。 7. 先用 `npx gt@latest translate --dry-run` 检查翻译范围，再针对约定的语言和范围运行 `npx gt@latest translate`。如果这会意外翻译大量内容或超出约定范围，请在提交前先与我确认。`gt translate` 还会写入 `gt-lock.json`，并在 `gt.config.json` 中写入 `_versionId`；请将两者一并提交。如果集成要求使用平台连接工作流，请改用该工作流。 ## 验证与收尾 运行类型检查（`npx tsc --noEmit`）和生产环境构建（`next build`）。仅当项目中已配置 lint 和测试时才运行它们。如果有可用的浏览器工具，请启动应用并验证实际的翻译效果：在源区域设置和目标区域设置之间切换、浏览页面、刷新页面，并检查插值和布局。如果请求既没有 `Accept-Language` 请求头也没有 cookie，则会渲染默认区域设置，并在每次查找翻译时记录一条 "gt-next: No locale could be determined" 警告；对于不带请求头的 curl 请求，这属于预期行为。如需检查某个目标区域设置，请发送 `Accept-Language: ` 或 `Cookie: generaltranslation.locale=`。如果与所选语言相关，请检查长文本和从右到左的布局。对于后端项目和内容项目，请检查实际的翻译响应或文件。如果未能执行浏览器验证，请勿声称已完成该验证。 在确认集成完成之前，请先修复初始化或运行时错误。遇到阻塞时，请查阅相关参考文档并检查命令报错，而不要反复重新创建项目或密钥。 对于使用预生成翻译的应用，请配置好生产环境工作流，确保翻译在现有构建之前执行，且生成的文件可在运行时使用。保留现有的构建步骤，在文档中注明 CI 密钥名称，并检查所选集成对本地文件或 CDN 的要求。如果翻译文件已提交且 CI 中没有密钥，请保持构建脚本不变。每当源文本发生变化时，使用已登录的会话在本地运行 `npx gt@latest translate`，然后提交 `public/_gt/.json`、`gt-lock.json` 和 `gt.config.json`。仅当 CI 中已设置具有文件写入和翻译队列权限的 `GT_API_KEY` 时，才将 `npx gt translate` 添加到构建脚本中。仅当所选 CDN 工作流需要时才使用 `--publish`。除非我明确要求，否则不要部署到生产环境，也不要合并拉取请求。 最后，请提供一份简明的交接说明：做了哪些更改、配置了哪个项目和哪些区域设置、如何运行、实际验证了哪些内容，以及我还需要完成哪些操作。请附上相关文档和 Dashboard 链接，但不要包含任何凭据。最终目标是：我的项目中的翻译能够正常运行，并且有清晰的方案来持续保持翻译更新。 ```` ## 即插即用智能体指南 [#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` - **TanStack Start** → `gt-tanstack-start` - **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 For a new setup, run from the app directory with `--no-interactive` and a flag for every question. Without `--no-interactive`, a missing answer opens a question in the terminal and the command waits for it; with it, a missing answer is an error that lists the flags still needed and changes no file: ```bash npx gt init --no-interactive --json --defaults --default-locale en --locales fr es --no-locadex --react-setup --file-formats none --no-dev-credentials ``` For a local Vite or TanStack Start setup, replace `--no-dev-credentials` with `--no-live-translations`. Do not pass both credential flag families. The wizard detects the framework, creates or updates `gt.config.json`, and can select/create a project and provision a development runtime key. Creating a project or key without a tooling key or saved login signs in first, which a person must approve. Framework rewrites are experimental and need review. Review [init flags and side effects](/docs/cli/reference/commands/init) before running it. 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. For a manually configured app, have the developer run `npx gt login`, then bind an existing project with `projectId` in the config or `GT_PROJECT_ID` in the environment. Login does not select a project or write env files; do not rerun init just to authenticate. For CI, commit the config and inject a separately scoped tooling key through the CI secret store: ```bash GT_API_KEY="your-api-key" # 授予整个 CLI 工作流所需的权限，而不仅限于生成 GT_PROJECT_ID="your-project-id" ``` CLI login, runtime development keys, and CI tooling keys are separate. SDKs do not read CLI sessions; init's development runtime key does not replace `GT_API_KEY`. Never commit keys or include them in deployed browser/mobile bundles. Read [CLI credentials](/docs/cli/guides/configuring#credentials) before configuring authentication. Require human approval for login and key creation; `--no-browser` and quiet mode do not make login unattended. ## Core usage Wrap user-facing JSX in ``. Write source copy directly — no translation keys needed: ```tsx import { T } from 'gt-next'; // or 'gt-react' // Everything inside is translated as a unit

Welcome to my app

; ``` 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 ; ``` 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 `` so they are not translated and never sent to the API. Use ``, ``, and `` for values that should be reformatted but not translated: ```tsx import { T, Var } from 'gt-next'; // Generates one translation, keeps the name unchanged Hello, {name}! ; ``` 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()` ``` Keep all locale configuration in `gt.config.json` — do not scatter locale lists across the codebase. ## Commands | Command | When to run | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `npx gt init` | Guided setup; runs headless with `--no-interactive` and flags. Can change framework files, dependencies, config, and runtime credentials. | | `npx gt configure` | Configuration without the React rewrite; accepts the same flags except framework setup. May install dependencies and provision runtime credentials. Write config manually for config-only changes. | | `npx gt login` | Have the developer approve account access for CLI work. | | `npx gt translate` | To translate the project via the General Translation API. Run in CI **before** building for production; add `--save-local` only when local edits should sync first. | | `npx gt generate` | To write source templates for manual translation without calling the API. Available for the supported packages listed in the [`gt generate`](/docs/cli/reference/commands/generate) reference. | | `npx gt translate --dry-run` | To inspect the translation scope without calling the API or writing translation files. | | `npx gt api --list` | To list the API operations bundled with the installed CLI. | | `npx gt api --spec ` | To inspect one bundled API operation by operation ID, specification path, or concrete request path. Omit the endpoint for the full specification. | | `npx gt api ` | To make an authenticated raw API request from a script or terminal. | | `npx gt project create --org-id --name --default-locale ` | With approval, create a project using a signed-in user or Organization key authorized for org:projects:create. | | `npx gt project status ` | To inspect a translation or project context-generation job. | 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 `` (or `useGT()`/`getGT()` for standalone strings) as you write it. - With authorization to send content for hosted translation, 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 ``, and add `context` when a string is ambiguous. - After deliberately editing a generated translation file, run `npx gt save-local` before downloading translations again, or pass `--save-local` to the next translation run. Don't: - Hardcode already-translated strings in the source, or add per-language `if`/`switch` branches — translate the source copy instead. - Edit generated translation files without syncing the changes; a later download can overwrite unsaved edits. - Commit or expose API keys, capture key-creation stdout in shared logs, or mint credentials without explicit approval. - Duplicate the locale configuration outside `gt.config.json`. ## Links - [`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) —— 区域设置、上下文，以及静态与动态内容。 - 账户命令：[`gt login`](/docs/cli/reference/commands/login) 和 [`gt api-key create`](/docs/cli/reference/commands/api-key-create)。 - 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 形式。 * [`agent-prompt.md`](/agent-prompt.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] 若需获取实时项目信息并进行上下文管理，请使用位于 `https://api.gtx.dev/mcp` 的托管 [Model Context Protocol](https://modelcontextprotocol.io) (MCP) 服务器。它采用可流式 HTTP。 该服务器的上下文管理工具可用于列出、创建和更新上下文组及其词汇表术语和自定义提示词，并支持导入导出和项目分配。这些工具与 [上下文管理 API](/docs/platform/openapi/reference/context-management/list-groups) 一一对应。 该托管服务器还提供 [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 键连接支持项目键 (`gtx-api-`) 和组织键 (`gtx-org-`)。现有的 `gtx-dev-` 键仍可作为项目键进行身份验证。每个工具都会针对所请求的操作检查键的权限。请为你的智能体所需的工具配置[自定义键权限](/docs/platform/dashboard/reference/api-keys)。 使用 `list_orgs` 查找组织 ID，使用 `list_projects` 查找项目 ID。这两个发现工具都无需任何资源权限。请将返回的 ID 作为 `orgId` 和 `projectId` 传给其他工具。项目键和组织键只能发现其所绑定的资源；项目键可以省略 `projectId`，此时将使用其自身所属的项目。 上下文管理工具需要 `org:context:read` 或 `org:context:write` 权限。请为组织键授予相应的 **Context** 权限，或在 MCP OAuth 登录时授予同等的组织 Context 访问权限。项目键无法使用这些工具。请将 `orgId` 传给 `list_context_groups` 和 `create_context_group`，并将 `groupId` 传给操作现有组的工具。 MCP 请求体的大小上限为 100 MiB。各个工具可能会对其输入设置更严格的大小限制。 连接完成后，让你的智能体使用 `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 工作，但翻译质量和配置仍然仍需人工把关。建议按以下方式分工： * **交给智能体：**用 [``](/docs/react/reference/components/t) 包裹面向用户的文案，为独立的字符串添加 [`useGT()`](/docs/react/reference/hooks/use-gt)，以及搭建 `gt.config.json` 的基础结构。使用 `--dev-credentials` 或 `--create-project` 运行 [`npx gt init`](/docs/cli/reference/commands/init) 前需先获得批准，因为这些选项会创建键或项目。 * **人工核查：**智能体编写的[翻译上下文](/docs/overview/key-concepts#context) (词汇表和自定义提示词) 、区域设置配置 (`defaultLocale` 和 `locales`) ，以及确认动态值或私密值已用 [``](/docs/react/reference/components/var) 包裹。 * **绝不要让智能体做：**未经批准生成或泄露凭据，编辑生成的翻译文件却不同步这些改动，或绕过 CLI 去硬编码已翻译好的字符串，而不是翻译源文案。 ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.