# gt: General Translation CLI tool: gt translate
URL: https://generaltranslation.com/zh/docs/cli/reference/commands/translate.mdx
Docs index: https://generaltranslation.com/llms.txt
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)。Lottie 动画必须先完成 stage，才能在之后下载，因为其布局处理是异步进行的。

*注意：仅用于 Production。请将 Production 环境的 `GT_API_KEY` 和 `GT_PROJECT_ID` 设置为环境变量，且绝不要将 API 密钥 存储在 `gt.config.json` 中。*

```bash
npx gt translate
```

## 工作原理 [#how-it-works]

1. 读取 `gt.config.json`，以确定目标区域设置、要翻译的文件及其输出路径。
2. 对于 `gt-next`、`gt-react`、`gt-react-native`、`gt-tanstack-start` 和 `gt-vue` 项目，会扫描你的 `src` glob 模式以查找内联内容。这包括 React 系列的 [`<T>`](/docs/react/reference/components/t) 组件和 [`useGT`](/docs/react/reference/hooks/use-gt) 调用，以及 Vue 模板和模块级的 [`t()`](/docs/vue/reference/functions/t) 调用，并包含你的词典文件。
3. 从 `package.json` 自动检测第三方 i18n 库——`next-intl` 或 `i18next` (支持 `i18next-icu`) ——并在遵循该库语法的同时翻译其 JSON 文件。
4. 使用 [`gt stage`](/docs/cli/reference/commands/stage) stage 收集到的内容：它会上传源内容，当设置了 `--save-local` 或 [`options.saveLocal: true`](/docs/cli/reference/config#save-local) 时，可选地检测并保存本地修改，然后将翻译任务加入队列。由于 Lottie 布局处理是异步的，当项目包含 `.lottie` 文件且 `stageTranslations` 为 `false` 时，流程会在此步骤之前退出，不会上传或将任何内容加入队列，并引导你使用拆分流程。
5. 使用 [`gt download`](/docs/cli/reference/commands/download) 下载结果。使用拆分后的命令可分别执行 stage 和下载。
6. 将翻译保存到你的代码库中；如果设置了 `--publish` 或 [`publish`](/docs/cli/reference/config#publish) 配置键，也会保存到 CDN。

默认情况下，CLI 不会在开始新工作前同步本地翻译修改。传入 `--save-local` 以同步这些修改，使用 `--force` 重新翻译所有内容，或使用 `--force-download` 仅重新下载而不重新翻译。

## 选项 [#flags]

| 参数                              | 描述                                                 | 类型         | 可选 | 默认值              |
| ------------------------------- | -------------------------------------------------- | ---------- | -- | ---------------- |
| `--api-key <key>`               | 生产环境 API 密钥。                                       | `string`   | 是  | `GT_API_KEY`     |
| `--project-id <id>`             | 项目 ID。                                             | `string`   | 是  | `GT_PROJECT_ID`  |
| `--version-id <id>`             | 已接受但不起作用；请参阅下方说明。                                  | `string`   | 是  | —                |
| `-c, --config <path>`           | 配置文件 的路径。                                          | `string`   | 是  | `gt.config.json` |
| `--default-locale <locale>`     | 项目的源区域设置。                                          | `string`   | 是  | `en`             |
| `--locales <locales...>`        | 额外的目标区域设置，会附加到配置中的 locales。                        | `string[]` | 是  | —                |
| `--timeout <seconds>`           | 等待翻译的超时时间 (秒) 。                                    | `number`   | 是  | `900`            |
| `--dry-run`                     | 仅解析并验证，不调用 API。                                    | `boolean`  | 是  | `false`          |
| `--force`                       | 重新翻译所有内容，覆盖现有翻译。                                   | `boolean`  | 是  | `false`          |
| `--force-download`              | 重新下载所有翻译，覆盖本地更改。                                   | `boolean`  | 是  | `false`          |
| `--save-local, --no-save-local` | 启用或禁用入队前保存本地修改。                                    | `boolean`  | 是  | `false`          |
| `--publish`                     | 将翻译发布到 CDN。                                        | `boolean`  | 是  | `false`          |
| `--enable-branching`            | 启用基于分支的跟踪。                                         | `boolean`  | 是  | —                |
| `--branch <branch>`             | 使用指定的分支名称，而不是自动检测。隐含启用 `--enable-branching`。       | `string`   | 是  | —                |
| `--disable-branch-detection`    | 仅使用指定分支，不检测关联关系。                                   | `boolean`  | 是  | `false`          |
| `--remote-name <name>`          | 用于分支检测的 Git 远程仓库名称。                                | `string`   | 是  | `origin`         |
| `--omit-config-ids`             | 不将 `_versionId` 或 `_branchId` 写入 `gt.config.json`。 | `boolean`  | 是  | —                |
| `--tag [value]`                 | 为本次运行添加标签；未提供值时，会自动从 git 解析。                       | `string`   | 是  | —                |
| `-m, --message <message>`       | 附加到翻译标签的消息。                                        | `string`   | 是  | —                |

### 源代码扫描选项 [#source]

这些选项适用于在 `gt-next`、`gt-react`、`gt-react-native`、`gt-tanstack-start` 和 `gt-vue` 项目中扫描源代码时使用。

| 参数                              | Description                                                                                            | Type       | Optional | Default     |
| ------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------- | -------- | ----------- |
| `--src <paths...>`              | source files 的 glob 模式。                                                                                | `string[]` | Yes      | 特定于框架的 glob |
| `--dictionary <path>`           | 词典文件的路径。                                                                                               | `string`   | Yes      | —           |
| `--tsconfig, --jsconfig <path>` | TS 或 JS 配置文件的路径。                                                                                       | `string`   | Yes      | 自动检测        |
| `--inline`                      | 包含内联内容，例如 [`<T>`](/docs/react/reference/components/t) 和 [`useGT`](/docs/react/reference/hooks/use-gt)。 | `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 使用特定于框架的默认值。React 系列项目会扫描 `src`、`app`、`pages` 和 `components`；Vue 项目还会涵盖根目录下的 `.vue` 文件以及 Vue 和 Nuxt 的约定目录。可通过 `--src` 或 [`src`](/docs/cli/reference/config#src) 配置键覆盖默认值。
* **词典：**未设置 `--dictionary` 时，CLI 会在 `./src` 和 `./` 中查找 `dictionary.[json|ts|js]`。
* **本地修改：**本地修改同步默认关闭。传入 `--save-local` 可对单次运行启用，或将 [`options.saveLocal`](/docs/cli/reference/config#save-local) 设置为 `true`。
* **覆盖：**`--force` 会覆盖所有现有翻译，并对新增翻译计费；`--force-download` 会用最新翻译覆盖本地修改，而不重新翻译。
* **Lottie：**使用 [`gt stage`](/docs/cli/reference/commands/stage) 翻译动画，然后重新运行 [`gt download`](/docs/cli/reference/commands/download)，直到所有区域设置均准备就绪。参见 [Lottie 格式参考](/docs/cli/reference/formats/lottie-files)。
* **添加标签：**添加标签是非阻塞的——如果创建标签失败，本次运行仍会继续。传入不带值的 `--tag` 时，将使用当前 Git commit hash 和提交信息。
* **发布：**使用 `--publish` 前，请先在你的项目“设置”中启用 CDN。如果 CDN 未启用，翻译会成功完成，但发布步骤会失败并显示警告。
* **分支：**传入 `--enable-branching` 可按 Git 分支跟踪翻译，或者传入 `--branch <name>`，后者会自动启用分支功能。未设置任一标志时，CLI 会回退到 `gt.config.json` 中的 `branchOptions.enabled`；若该项未设置，则默认关闭。参见 [按分支跟踪翻译](/docs/cli/guides/branching)。
* **`--version-id` 不起作用。**该标志会被解析，但没有任何内容会读取它：版本 ID 是按文件内容 hash 生成的，而需要运行级版本的命令会从 `gt.config.json` 中读取 `_versionId`。请改为在那里设置 [`_versionId`](/docs/cli/reference/config)。
* **安全性：**绝不要将你的 API 密钥存储在 `gt.config.json` 中。CLI 会自动从环境变量中读取 `GT_API_KEY` 和 `GT_PROJECT_ID`。

### 版本历史

| 版本       | 变更                                    |
| -------- | ------------------------------------- |
| `2.20.3` | 本地修改改为选择性启用；使用 `--save-local` 启用该步骤。  |
| `2.16.1` | 默认保存本地修改；可通过 `--no-save-local` 禁用此行为。 |

## Sitemap

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