# gt: General Translation CLI tool: 快速入门
URL: https://generaltranslation.com/zh/docs/cli/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 使用 General Translation CLI 通过命令行翻译你的项目。

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 访问**，通过 [`gt api`](/docs/cli/reference/commands/api) 发起经过身份验证的原始请求，并使用内置的 OpenAPI 发现功能。
* **验证**，用于在不调用 API 的情况下检查项目中的翻译错误。

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

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

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

## 快速入门 [#quickstart]

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

### 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 init`](/docs/cli/reference/commands/init)，自动检测你的框架并创建 `gt.config.json`，还可以选择创建项目和开发密钥。如果某个步骤需要登录，向导会引导你完成登录。

```bash
npx gt init
```

在 monorepo 中，请在要本地化的应用目录下运行该命令。如果在工作区根目录下运行，向导会直接退出，不会修改任何文件。

<Callout type="warn">
  在没有终端的环境中，[`gt init`](/docs/cli/reference/commands/init) 不会显示交互提示。如果缺少必要的答案，它会在修改文件之前停止，并列出需要传入的选项；参见[无界面运行](/docs/cli/reference/commands/init#headless)。在 CI 中，请参阅 [CI 非交互式设置](#ci-setup)。
</Callout>

向导会设置默认区域设置和目标区域设置，并选择翻译的存储位置。它还可以将开发密钥和项目 ID 写入 `.env.local`。完整命令说明请参见 [`gt init`](/docs/cli/reference/commands/init)。

*注意：此时项目根目录下应已生成 `gt.config.json`。采用本地打包方式的 Vite 设置可以跳过登录和凭据配置；开始翻译之前，请先完成下一步。*

### 3. 检查你的凭据

[`translate`](/docs/cli/reference/commands/translate) 命令需要项目 ID，以及你已保存的登录信息或 API Key。如果初始化时跳过了这些配置，请运行 [`gt login`](/docs/cli/reference/commands/login) 并设置你的项目 ID：

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

 (请参阅 [CLI 凭据](/docs/cli/guides/configuring#credentials)) 。

### 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 Key和项目 ID 设置为 CI 提供商 secret 设置中的环境变量，而不是写入已提交的文件中。请在 [Dashboard](/docs/platform/dashboard/reference/api-keys) 中或通过 [`gt api-key create`](/docs/cli/reference/commands/api-key-create) 创建该密钥，并授予 **Files &gt; Write** 和 **Translation queue &gt; Enabled** 权限 (如需生成上下文，还需添加 **Context &gt; Write**) ；向导生成的开发密钥权限不足。

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

## Sitemap

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