# 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`，配置你的项目，并进行首次翻译。

### 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
```

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

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

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

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

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

### 4. 翻译项目

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

```bash
npx gt translate
```

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

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