# gt: General Translation CLI tool: Translate
URL: https://generaltranslation.com/zh/docs/cli/translate.mdx
---
title: Translate
description: 如何翻译项目
---
## 用法
```bash
npx gt translate
```
**重要：** 请在 CI 流水线中于生产环境构建应用**之前**运行此操作。
## 概述
`gt translate` 命令会读取你的 `gt.config.json` 文件，以确定需要翻译哪些文件，然后翻译你的项目。
如果你使用的是 [`gt-next`](/docs/next)、[`gt-react`](/docs/react) 或 [`gt-react-native`](/docs/react-native)，它还会扫描项目源代码中的内联内容 (例如 `` 组件和 `useGT` Hook) ，并生成所需的翻译文件。
此外，如果提供了字典文件，它也会将其中的内容包含在内。
此命令是使用 General Translation API 及相关服务的主要方式。
**仅限生产环境使用：** 此命令用于生产构建，**不应在开发环境中使用**。
运行此命令前，请确保你当前所在的分支将用于生产环境。
请将生产环境 API 密钥 (`GT_API_KEY`) 和项目 ID (`GT_PROJECT_ID`) 设置为环境变量。
**注意：** 需要提供生产环境 API 密钥。可在 [generaltranslation.com](https://generaltranslation.com/dashboard) 免费获取，或运行[设置向导](/docs/cli/init)来生成一个。
### 使用 translate 翻译项目 [#translate]
```bash
npx gt translate
```
`translate` 命令会读取你的 `gt.config.json` 来确定需要翻译哪些文件，扫描项目源代码中的可翻译内容，并生成所需的翻译文件。
翻译内容会自动保存到你的代码库中。
更多详情，请参阅 [配置文档](/docs/cli/reference/config#files)。
{/* These links point to our own SDK docs intentionally — we want to show how our CLI handles these libraries, not link to the external library sites */}
**自动检测：** 如果你使用的是 [`next-intl`](/docs/next)、[`react-i18next`](/docs/react) 或
[`next-i18next`](/docs/react-native)，CLI 工具会通过读取你的 `package.json` 文件自动检测
你使用的 i18n 库，并在翻译 JSON 文件时遵循该 i18n 库的语法。
### 仅验证，不进行翻译 [#validate]
```bash
npx gt translate --dry-run
```
如果你使用的是 [`gt-next`](/docs/next)、[`gt-react`](/docs/react) 或 [`gt-react-native`](/docs/react-native)，可以使用此方法在不生成任何翻译的情况下验证项目中的 `` 组件和字典文件。
***
## 标志
| 参数 | 说明 | 类型 | 默认值 |
| ------------------------------- | --------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `--api-key` | 指定生产环境 API 密钥 | `string` | |
| `--project-id` | 指定项目 ID | `string` | |
| `--version-id` | 指定版本 ID (默认为内容的哈希) | `string` | |
| `--config ` | 指定 GT 配置文件的路径 | `string` | `"gt.config.json"` |
| `--tsconfig, --jsconfig ` | 指定 TS 或 JS 配置文件的路径 | `string` | |
| `--src ` | 用空格分隔的源文件 glob 模式 (相对于根目录) | `[string]` | `['src/**/*.{js,jsx,ts,tsx}', 'app/**/*.{js,jsx,ts,tsx}', 'pages/**/*.{js,jsx,ts,tsx}', 'components/**/*.{js,jsx,ts,tsx}']` |
| `--dictionary ` | 指定字典文件的路径 | `string` | |
| `--inline` | 除字典外，还包含内联 `` 标签 | `boolean` | `true` |
| `--timeout` | 翻译请求的超时时间 (秒) | `number` | `900` |
| `--new, --locales ` | 要翻译到的区域设置 (会追加到 `gt.config.json` 的 locales 中) | `[string]` | |
| `--default-locale ` | 项目的源区域设置 | `string` | `en` |
| `--ignore-errors` | 忽略错误，并强制翻译有效内容 | `标志` | `false` |
| `--dry-run` | 仅验证，不执行翻译 | `标志` | `false` |
| `--force` | 强制重新翻译所有内容 | `标志` | `false` |
| `--force-download` | 强制下载所有译文 | `标志` | `false` |
| `--save-local` | 在将译文加入队列前，检测并保存 local edits | `标志` | `false` |
| `--enable-branching` | 为项目启用分支功能 | `标志` | `false` |
| `--branch ` | 为译文指定自定义分支名称 | `string` | |
| `--disable-branch-detection` | 禁用自动分支检测 | `标志` | `false` |
| `--tag [value]` | 为此次翻译运行添加标签 (如果未提供值，则自动从 git 解析) | `string` | |
| `-m, --message ` | 要附加到翻译标签的消息 | `string` | |
| `--publish` | 翻译后将译文发布到 CDN | `标志` | `false` |
| `--remote-name ` | 为分支检测指定自定义远程名称 | `string` | `"origin"` |
**安全：**不要将你的 API 密钥添加到 `gt.config.json` 文件中！请改为将其设置为环境变量。CLI 会在设置后自动读取 `GT_API_KEY`。
### 关键标志
| 标志 | 说明 |
| -------------------- | -------------------------------------------------------------------- |
| `--dry-run` | 在不与 GT API 通信的情况下解析并验证你的项目。适合用于验证你的代码库。 |
| `--force` | 重新翻译所有内容，并覆盖现有译文。任何本地更改都会丢失。新生成的译文将产生费用。 |
| `--force-download` | 重新下载所有译文，并覆盖本地更改。不会重新翻译。 |
| `--save-local` | 在入队前检测并保存翻译文件中的 local edits。参见 [`save-local`](/docs/cli/save-local)。 |
| `--enable-branching` | 按不同的 git 分支分别跟踪译文。参见 [分支功能](/docs/cli/branching)。 |
| `--tag` | 为一次翻译运行添加一个便于人工识别的标识符，用于版本跟踪。参见 [标签](#tagging)。 |
| `-m, --message` | 为翻译标签附加一条说明消息。参见 [标签](#tagging)。 |
| `--publish` | 将译文公开到 CDN 以供 runtime 加载。参见 [公开到 CDN](#publishing-to-the-cdn)。 |
### 配置文件
首次运行 CLI 时，它会尝试在项目根目录下创建一个 `gt.config.json` 文件。有关配置的更多信息，请参阅[这里](/docs/cli/reference/config)。
## 重要提示
### 内容来源
`translate` 命令会递归搜索项目中的可翻译内容。
默认会搜索以下目录：
* `./src`
* `./app`
* `./pages`
* `./components`
你可以通过 `--src` 标志指定其他目录，
或者修改 [`gt.config.json`](/docs/cli/reference/config) 中的 `src` 属性。
### 覆盖译文
默认情况下，CLI 不会覆盖本地对译文所做的修改，除非源内容发生了变化。
如需重新翻译已翻译的内容，请使用 `--force`。
**注意：** `--force` 会 **覆盖所有现有译文并生成新的译文**。任何本地修改都会丢失。新的翻译将会产生费用。
如需在不重新翻译的情况下重新下载译文，请使用 `--force-download`。
**注意：** `--force-download` 会覆盖本地对译文所做的修改，并拉取最新的译文。它不会重新翻译任何内容。
### 标签 [#tagging]
使用 `--tag` 和 `-m` 标志为翻译运行添加便于阅读的标识符，方便在仪表板中跟踪并区分不同版本。
#### 使用自定义标识符标签
```bash
npx gt translate --tag v2.1.0
```
#### 使用自定义标识符和消息进行标签
```bash
npx gt translate --tag v2.1.0 -m "Added checkout page translations"
```
#### 基于 git 自动打标签
传入不带值的 `--tag` 后，会自动将当前 git commit 的 哈希值 用作标签 id，并将 commit 消息用作标签消息：
```bash
npx gt translate --tag
```
你可以用自定义提交信息覆盖原提交信息：
```bash
npx gt translate --tag -m "Release 2.1 translations"
```
#### 仅消息标签
如果传入 `-m` 但不传入 `--tag`，系统会根据当前 git commit 的哈希值自动生成一个标签 (如果不在 git 仓库中，则会使用随机标识符) ：
```bash
npx gt translate -m "Weekly translation update"
```
标签操作是非阻塞的——即使标签创建失败，翻译流程也会正常继续。
### 发布到 CDN [#publishing-to-the-cdn]
默认情况下，`gt translate` 会将翻译文件保存在本地代码库中。使用 `--publish` 标志还可将译文发布到 General Translation CDN，从而无需将文件打包进应用，即可启用 runtime 翻译加载。
```bash
npx gt translate --publish
```
这对于 `gt-next` 项目很有用：这类项目会在 runtime 从 CDN 加载译文，而不是从本地文件加载。
**必须启用 CDN：**使用 `--publish` 之前，请先在 [generaltranslation.com/dashboard](https://generaltranslation.com/dashboard) 的项目设置中启用 CDN。如果未启用 CDN，该命令会成功完成翻译，但在发布时会失败并发出警告。
你可以将 `--publish` 与本地文件输出结合使用——译文会保存在本地，*同时*也会发布到 CDN：
```bash
npx gt translate --publish
```
### 字典文件
`translate` 命令会自动检测项目中的字典文件。
默认情况下，它会在以下位置查找名为 `dictionary.[json|ts|js]` 的文件：
* `./src`
* `./`
你可以使用 `--dictionary` 标志指定其他字典文件，或修改 [`gt.config.json`](/docs/cli/reference/config) 中的 `dictionary` 属性。