# gt: General Translation CLI tool: gt translate URL: https://generaltranslation.com/zh/docs/cli/reference/commands/translate.mdx --- title: gt translate description: 通过 General Translation API 翻译项目。gt translate 命令的 API 参考。 --- 翻译你的项目。它会读取 `gt.config.json` 来定位文件；当你使用框架库时，会扫描源代码中的内联内容；还会包含你的 词典，并将译文保存到代码库或 CDN。 这是使用 General Translation API 的主要命令。请在 CI 中于 Production 构建前运行它。有关完整工作流，请参阅[生成译文](/docs/cli/guides/generating-translations)。在底层，`translate` 会在一步中完成 `stage` 和下载；如果要将这些步骤分开运行，请使用 [`gt stage`](/docs/cli/reference/commands/stage)、[`gt upload`](/docs/cli/reference/commands/upload)、[`gt enqueue`](/docs/cli/reference/commands/enqueue) 和 [`gt download`](/docs/cli/reference/commands/download)。 *注意：仅用于 Production。请将 Production 环境的 `GT_API_KEY` 和 `GT_PROJECT_ID` 设置为环境变量，且绝不要将 API 密钥 存储在 `gt.config.json` 中。* ```bash npx gt translate ``` ## 工作原理 [#how-it-works] 1. 读取 `gt.config.json`，以确定目标 locales、要翻译的文件及其输出路径。 2. 对于 `gt-next`、`gt-react`、`gt-react-native` 和 `gt-tanstack-start` 项目，会扫描你的 `src` glob 以查找内联内容——[``](/docs/react/reference/components/t) 组件和 [`useGT`](/docs/react/reference/hooks/use-gt) 调用——并包含你的词典文件。 3. 从 `package.json` 自动检测第三方 i18n 库——`next-intl` 或 `i18next` (支持 `i18next-icu`) ——并在遵循该库语法的同时翻译其 JSON 文件。 4. 一步完成将收集到的内容暂存并下载结果。内部实际执行的是 [`gt stage`](/docs/cli/reference/commands/stage) 和 [`gt download`](/docs/cli/reference/commands/download)；如果你想分别执行这两部分，请使用拆分后的命令。 5. 将翻译保存到你的代码库中；如果设置了 `--publish` 或 [`publish`](/docs/cli/reference/config#publish) 配置键，也会保存到 CDN。 默认情况下，CLI 不会覆盖本地翻译更改，除非源内容已发生变化。使用 `--force` 重新翻译所有内容，或使用 `--force-download` 仅重新下载而不重新翻译。 ## 选项 [#flags] | 参数 | 描述 | 类型 | 可选 | 默认值 | | ---------------------------- | -------------------------------------------------- | ---------- | -- | ---------------- | | `--api-key ` | 生产环境 API 密钥。 | `string` | 是 | `GT_API_KEY` | | `--project-id ` | 项目 ID。 | `string` | 是 | `GT_PROJECT_ID` | | `--version-id ` | 本次运行的版本 ID。 | `string` | 是 | 内容哈希 | | `-c, --config ` | config file 的路径。 | `string` | 是 | `gt.config.json` | | `--default-locale ` | 项目的源区域设置。 | `string` | 是 | `en` | | `--locales ` | 额外的目标区域设置，会附加到配置中的 locales。 | `string[]` | 是 | — | | `--timeout ` | 等待翻译的超时时间 (秒) 。 | `number` | 是 | `900` | | `--dry-run` | 仅解析并验证，不调用 API。 | `boolean` | 是 | `false` | | `--force` | 重新翻译所有内容，覆盖现有翻译。 | `boolean` | 是 | `false` | | `--force-download` | 重新下载所有翻译，覆盖本地更改。 | `boolean` | 是 | `false` | | `--save-local` | 入队前保存本地编辑。 | `boolean` | 是 | `false` | | `--publish` | 将翻译发布到 CDN。 | `boolean` | 是 | `false` | | `--enable-branching` | 启用基于分支的跟踪。 | `boolean` | 是 | `false` | | `--branch ` | 使用指定的分支名称，而不是自动检测。 | `string` | 是 | — | | `--disable-branch-detection` | 仅使用指定分支，不检测关联关系。 | `boolean` | 是 | `false` | | `--remote-name ` | 用于分支检测的 Git 远程仓库名称。 | `string` | 是 | `origin` | | `--omit-config-ids` | 不将 `_versionId` 或 `_branchId` 写入 `gt.config.json`。 | `boolean` | 是 | — | | `--tag [value]` | 为本次运行添加标签；未提供值时，会自动从 git 解析。 | `string` | 是 | — | | `-m, --message ` | 附加到翻译标签的消息。 | `string` | 是 | — | ### 源码扫描选项 [#source] 这些选项适用于在 `gt-next`、`gt-react`、`gt-react-native` 和 `gt-tanstack-start` 项目中扫描源码时使用。 | Parameter | Description | Type | Optional | Default | | ------------------------------- | -------------------------- | ---------- | -------- | --------------------------------------- | | `--src ` | source files 的 glob 模式。 | `string[]` | Yes | `src`、`app`、`pages`、`components` 的 glob | | `--dictionary ` | 词典 file 的路径。 | `string` | Yes | — | | `--tsconfig, --jsconfig ` | TS 或 JS 配置文件的路径。 | `string` | Yes | 自动检测 | | `--inline` | 包含内联内容，例如 `` 和 `useGT`。 | `boolean` | Yes | `true` | | `--ignore-errors` | 忽略扫描内联内容时发现的错误。 | `boolean` | Yes | `false` | ### 实验性选项 [#experimental] | 参数 | 描述 | 类型 | 可选 | 默认值 | | ----------------------------------------- | --------------------------------- | --------- | -- | ------- | | `--experimental-localize-static-urls` | 对已翻译的 `md`/`mdx` 文件中的 URL 进行本地化。 | `boolean` | 是 | `false` | | `--experimental-hide-default-locale` | 在本地化路径中隐藏默认区域设置。 | `boolean` | 是 | `false` | | `--experimental-flatten-json-files` | 将 JSON 文件展平为单个文件。 | `boolean` | 是 | `false` | | `--experimental-localize-static-imports` | 对 `md`/`mdx` 文件中的静态导入进行本地化。 | `boolean` | 是 | `false` | | `--experimental-localize-relative-assets` | 重写已翻译的 `md`/`mdx` 文件中的相对图片资源 URL。 | `boolean` | 是 | `false` | | `--experimental-clear-locale-dirs` | 下载前清空区域设置目录。 | `boolean` | 是 | `false` | ## 示例 [#example] ```bash # 使用 gt.config.json 进行翻译，从环境变量中读取 GT_API_KEY 和 GT_PROJECT_ID npx gt translate # 解析并验证项目，不调用 API npx gt translate --dry-run # 将翻译保存到本地并发布至 CDN，以供运行时加载 npx gt translate --publish # 为本次运行添加标签，便于在仪表板中识别 npx gt translate --tag v2.1.0 -m "Added checkout page translations" ``` ## 其他说明 [#notes] * **内容来源：**CLI 默认扫描 `src`、`app`、`pages` 和 `components`。可通过 `--src` 或 [`src`](/docs/cli/reference/config#src) 配置键覆盖默认值。 * **词典：**未设置 `--dictionary` 时，CLI 会在 `./src` 和 `./` 中查找 `dictionary.[json|ts|js]`。 * **覆盖：**`--force` 会覆盖所有现有翻译，并对新增翻译计费；`--force-download` 会用最新翻译覆盖本地修改，而不重新翻译。 * **添加标签：**添加标签是非阻塞的——如果创建标签失败，本次运行仍会继续。传入不带值的 `--tag` 时，将使用当前 Git commit hash 和提交信息。 * **发布：**使用 `--publish` 前，请先在你的项目“设置”中启用 CDN。如果 CDN 未启用，翻译会成功完成，但发布步骤会失败并显示警告。 * **分支：**传入 `--enable-branching` 可按 Git 分支跟踪翻译。参见 [按分支跟踪翻译](/docs/cli/guides/branching)。 * **安全性：**绝不要将你的 API 密钥存储在 `gt.config.json` 中。CLI 会自动从环境变量中读取 `GT_API_KEY` 和 `GT_PROJECT_ID`。