# gt: General Translation CLI tool: YAML
URL: https://generaltranslation.com/zh/docs/cli/formats/yaml.mdx
---
title: YAML
description: 如何用 General Translation 自动翻译 YAML 文件
---

## 概述

无论你使用的是哪种 i18n 库，`gt` 都可以自动翻译项目中的 YAML 文件。

<Callout type="info">
  **注意：** 我们目前支持以下第三方 i18n 库的自定义字符串语法和格式：
  `next-intl`、`i18next`。如果你使用的是其他 i18n 库，对于包含自定义语法和格式的字符串 (例如
  ICU 消息) ，翻译结果可能不够准确。没看到你常用的库？[请告诉我
  们](https://github.com/generaltranslation/gt/issues)，我们会尽快添加支持！
</Callout>

我们将按以下 4 个步骤进行：

<Steps>
  <Step>
    添加环境变量
  </Step>

  <Step>
    安装 [`gt`](/docs/cli)
  </Step>

  <Step>
    创建 `gt.config.json` 文件
  </Step>

  <Step>
    运行 [`gt translate`](/docs/cli/translate#translate)
  </Step>
</Steps>

***

## 第 1 步：添加环境变量

将生产环境的 API 密钥和项目 ID 添加到环境变量中。
这是使用 `gt` 工具的必要步骤。
这些信息可在 [General Translation 仪表板](https://generaltranslation.com/dashboard) 中获取。

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


## 第 2 步：安装 `gt`

在项目中安装 `gt` 工具。

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt
    ```
  </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>

## 第 3 步：创建 `gt.config.json` 文件

在项目根目录下创建一个 `gt.config.json` 文件。

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["zh", "es", "ja"],
  "files": {
    "yaml": {
      "include": ["i18n/[locale]/*.yaml"]
    }
  }
}
```

你可以根据实际需要自定义 `gt.config.json` 文件。更多信息请参阅[配置](/docs/cli/reference/config)文档。

更新 `yaml` 文件格式，使其中的 `include` 路径与你的项目结构相匹配。支持 `.yaml` 和 `.yml` 两种扩展名。

<Callout>翻译会保留原始字符串语法。</Callout>

## 第 4 步：将 `gt translate` 命令加入构建流程

在执行构建命令前，将 `gt translate` 命令加入你的构建或 CI 流程，以自动为项目添加翻译。

```json title="package.json"
{
  "scripts": {
    "translate": "npx gt translate",
    "build": "npm run translate && <your build command>"
  }
}
```

这会为你的所有区域设置生成翻译，并将其保存到项目中。
如果你想把这些文件提交到仓库，也可以改为在提交前运行此命令。

这样就完成了！现在，每当项目发生变化时，项目都会自动更新你的所有翻译 YAML 文件。

***


## 键级元数据

你可以使用配套的 `.metadata.yaml` 文件，为各个字符串单独附加翻译说明。这样，无需修改源文件，就能为特定键提供上下文、字符限制和源代码上下文。

```yaml title="translations.yaml"
nav:
  home: "Home"
  bank: "Bank"
  save: "Save"
alerts:
  new_lead: "You have a new lead!"
```

```yaml title="translations.metadata.yaml"
nav:
  bank:
    context: "河岸——河流的岸边。不是金融机构。"
  save:
    context: "体育术语——守门员扑救阻止进球。不是保存数据。"
    maxChars: 12
alerts:
  new_lead:
    context: "销售/CRM 场景。'lead' 指潜在客户。"
    maxChars: 30
```

并非每个键都需要元数据——只需为需要特定翻译说明的键提供相应条目。

完整的受支持字段列表，请参阅[键级元数据参考](/docs/cli/reference/keyed-metadata)。

***


## 注意事项

* 你可以使用 [`gt translate`](/docs/cli/translate#translate) 命令，自动将翻译添加到项目中。
* 如果你想提交翻译文件，应在提交前先运行 `gt translate` 命令。
* 如需配置翻译输出路径，请参阅[配置](/docs/cli/reference/config)文档。
* `.yaml` 和 `.yml` 扩展名均受支持。

## 后续步骤

* 有关 CLI 用法的详细信息，请参阅[translate 命令](/docs/cli/translate)。
* 了解用于为各个键提供翻译说明的[键级元数据](/docs/cli/reference/keyed-metadata)。