# gt: General Translation CLI tool: 快速入门
URL: https://generaltranslation.com/zh/docs/cli/quickstart.mdx
---

title: 快速入门
description: 了解 General Translation CLI (`gt`) 的作用、适用场景，以及如何翻译你的第一个项目。
related:
  links:
    - /docs/cli/guides/generating-translations
    - /docs/cli/guides/configuring
    - /docs/cli/guides/managing-translations
    - /docs/cli/guides/using-auto-jsx

---

General Translation CLI (`gt`) 可通过命令行为你的项目设置国际化并执行翻译。

它适用于 [`gt-react`、`gt-next` 和 `gt-react-native`](/docs/react/overview)，也兼容 `next-intl` 和 `i18next` 等第三方 i18n 库，以及 JSON、YAML、Markdown 和 MDX 等独立文件。

## CLI 的作用 [#what-it-does]

CLI 让你可以直接使用以下功能：

* **设置**，用于安装依赖、完成框架集成，并创建 `gt.config.json`。
* **翻译**，用于将源内容发送到 General Translation API，并将结果保存到你的代码库或 CDN。
* **CI 构建模块**，用于在不同的流水线阶段执行上传、排队和下载翻译。
* **验证**，用于在不调用 API 的情况下检查项目中的翻译错误。

## 何时使用 CLI [#when-to-use]

当你需要以下操作时，请使用 CLI：

* 通过引导式向导为新项目配置翻译。
* 在构建或 CI 流水线中翻译你的项目。
* 无需添加框架库即可翻译独立的内容文件。
* 将翻译与源内容一起纳入版本控制。

## 快速入门 [#quickstart]

安装 `gt`，配置你的项目，并进行首次翻译。你需要一个现有项目，其中包含 `package.json`，并且已安装 Node.js。

### 1. 安装 `gt`

将 CLI 作为开发依赖安装。

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt --save-dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

### 2. 配置项目

运行设置向导，检测你的框架、创建 `gt.config.json`，并在所选设置需要时生成凭据。

```bash
npx gt init
```

在 monorepo 中，请从要本地化的应用目录运行该命令。如果从工作区根目录运行，向导会停止，且不会更改任何文件。

<Callout type="warn">
  [`gt init`](/docs/cli/reference/commands/init) 是一个交互式向导，需要在终端中运行。在 CI 或其他非交互式 shell 中，它可能会等待输入、验证失败，或在未创建 `gt.config.json` 或未写入凭据的情况下提前退出。对于这些环境，请使用[面向 CI 的非交互式设置](#ci-setup)。
</Callout>

该向导会设置你的默认区域设置和目标区域设置，并选择翻译的存储位置。当所选设置需要凭据时，它可以将 API 密钥和项目 ID 写入 `.env.local`。如需了解详细设置，请参阅[配置 CLI](/docs/cli/guides/configuring)；完整命令请参见 [`gt init`](/docs/cli/reference/commands/init)。

*注意：你现在应该已经在项目根目录下拥有一个 `gt.config.json`。如果向导生成了凭据，`.env.local` 会包含 `GT_API_KEY` 和 `GT_PROJECT_ID`。本地打包的 Vite 设置会跳过凭据，因此请在翻译前的下一步中添加它们。*

### 3. 添加你的生产环境 API 密钥

[`translate`](/docs/cli/reference/commands/translate) 命令需要生产环境 API 密钥和项目 ID。你可以让向导为你生成它们，也可以在 [API Keys 页面](https://generaltranslation.com/dashboard) 上自行创建。请将它们设置为环境变量，以便 CLI 读取。

```bash title=".env.local"
GT_API_KEY=your-api-key
GT_PROJECT_ID=your-project-id
```

*注意：请将 API 密钥设为环境变量，切勿将其添加到 `gt.config.json` 中。*

### 4. 翻译项目

运行 [`translate`](/docs/cli/reference/commands/translate) 命令，翻译 `gt.config.json` 中配置的所有文件，以及源代码中所有内联的 [`<T>`](/docs/react/reference/components/t) 组件和词典条目。

```bash
npx gt translate
```

翻译内容会保存到你的代码库中，可直接提交。请在构建生产环境版本之前，先在你的 CI 流水线中运行此命令。完整流程请参见[生成翻译](/docs/cli/guides/generating-translations)。

## CI 的非交互式设置 [#ci-setup]

设置向导需要交互式终端，因此无法在 CI 或其他非交互式环境中运行。请手动进行设置：提交 `gt.config.json`，通过环境变量提供凭据，并针对该配置运行 [`translate`](/docs/cli/reference/commands/translate)。

### 1. 添加 `gt.config.json`

自行编写并提交此文件，这样 CLI 才知道要翻译哪些内容。最小配置需要设置 source 和目标区域设置，并添加一个 `files` 条目，让 [`translate`](/docs/cli/reference/commands/translate) 有内容可处理。下面的 `gt` 条目会将框架翻译 (来自 `gt-next`、`gt-react` 或 `gt-react-native`) 存储到指定路径的本地。

```json title="gt.config.json"
{
  "$schema": "https://assets.gtx.dev/config-schema.json",
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "public/_gt/[locale].json"
    }
  }
}
```

如果要改为翻译独立文件，请添加一种文件类型 (例如 `json` 或 `mdx`) ，并用带有 `include` glob 的配置替换 `gt` 条目，或与其一同使用。有关文件和存储选项，请参阅[配置 CLI](/docs/cli/guides/configuring)；有关所有字段，请参阅[配置参考](/docs/cli/reference/config)。

### 2. 设置你的凭据

请将你的生产环境 API 密钥和项目 ID 设置为 CI 提供商 secret 设置中的环境变量，而不是写入已提交的文件中。请在 [API Keys 页面](https://generaltranslation.com/dashboard) 上创建它们。

```bash
GT_API_KEY=your-api-key
GT_PROJECT_ID=your-project-id
```

### 3. 运行 `translate` 命令

在为生产环境执行 `build` 之前，请先运行 [`translate`](/docs/cli/reference/commands/translate)。传入 `--config` 参数以指定你的配置文件。

```bash
npx gt translate --config gt.config.json
```
## Next steps

- /docs/cli/guides/generating-translations
- /docs/cli/guides/configuring
- /docs/cli/guides/managing-translations
- /docs/cli/guides/using-auto-jsx