---
title: 带有根键的 YAML
subtitle: 使用 Lingo.dev CLI 对带有语言环境根键的 YAML 文件进行 AI 翻译
---

## 什么是带有根键的 YAML？

带有根键的 YAML 是一种本地化格式，其中每个语言环境的翻译都组织在以语言环境代码命名的根级键下。这种格式允许在相同的目录结构中存储多个语言环境，同时按语言进行组织。

例如：

```yaml
en:
  navigation:
    home: "首页"
    about: "关于我们"
    contact: "联系我们"
  forms:
    title: "联系表单"
    name_label: "您的姓名"
    submit_button: "发送消息"
```

## 什么是 Lingo.dev CLI？

**Lingo.dev CLI** 是一个免费的开源命令行工具，用于使用 AI 翻译应用程序和内容。它旨在取代传统的翻译管理软件，同时与现有的流水线集成。

要了解更多信息，请参阅[概述](/cli)。

## 关于本指南

本指南解释了如何使用 **Lingo.dev CLI** 翻译带有语言环境根键的 YAML 文件。

您将学习如何：

- 从头开始创建项目
- 配置翻译流水线
- 使用 AI 生成翻译

## 前提条件

要使用 **Lingo.dev CLI**，请确保已安装 Node.js v18+：

```bash
❯ node -v
v22.17.0
```

## 第 1 步：设置项目

在项目的目录中，创建一个 `i18n.json` 文件：

```json
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}
```

此文件定义了翻译流水线的行为，包括要翻译的语言以及文件系统中可本地化内容的位置。

要了解更多可用属性，请参阅 [i18n.json](/cli/i18n-json-configuration)。

## 第 2 步：配置源语言环境

_源语言环境_ 是您的内容所使用的原始语言和地区。要配置源语言环境，请在 `i18n.json` 文件中设置 `locale.source` 属性：

```json
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}
```

源语言环境必须以 [BCP 47 语言标签](https://developer.mozilla.org/en-US/docs/Glossary/BCP_47_language_tag) 的形式提供。

有关 **Lingo.dev CLI** 支持的语言环境代码的完整列表，请参阅[支持的语言环境代码](/cli/supported-locales)。

## 第 3 步：配置目标语言环境

_目标语言环境_ 是指您希望将内容翻译成的语言和地区。要配置目标语言环境，请在 `i18n.json` 文件中设置 `locale.targets` 属性：

```json
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}
```

## 第 4 步：创建源内容

如果尚未创建，请创建一个或多个包含待翻译内容的以语言环境为根键的 YAML 文件。这些文件必须位于路径中包含源语言环境的路径中（例如，作为目录名称如 `en/` 或作为文件名的一部分如 `messages.en.yml`）。

## 第 5 步：创建存储桶

1. 在 `i18n.json` 文件中，向 `buckets` 对象添加一个 `"yaml-root-key"` 对象：

    ```json
    {
      "$schema": "https://lingo.dev/schema/i18n.json",
      "version": "1.10",
      "locale": {
        "source": "en",
        "targets": ["es"]
      },
      "buckets": {
        "yaml-root-key": {}
      }
    }
    ```

2. 在 `"yaml-root-key"` 对象中，定义一个或多个 `include` 模式的数组：

    ```json
    {
      "$schema": "https://lingo.dev/schema/i18n.json",
      "version": "1.10",
      "locale": {
        "source": "en",
        "targets": ["es"]
      },
      "buckets": {
        "yaml-root-key": {
          "include": ["./[locale]/example.yml"]
        }
      }
    }
    ```

   这些模式定义了需要翻译的文件。

   模式本身：

   - 必须包含 `[locale]` 作为配置语言环境的占位符
   - 可以指向文件路径（例如，`"[locale]/translations.yml"`）
   - 可以使用星号作为通配符占位符（例如，`"[locale]/*.yml"`）

   不支持递归的 glob 模式（例如，`**/*.yml`）。

## 第 6 步：配置 LLM

**Lingo.dev CLI** 使用大型语言模型（LLM）通过 AI 翻译内容。要使用这些模型之一，您需要从支持的提供商处获取 API 密钥。

为了尽快开始使用，我们推荐使用 **Lingo.dev Engine** —— 我们自己的托管平台，每月提供 10,000 个免费令牌：

1. [注册一个 Lingo.dev 账户](/auth)。
2. 运行以下命令：

   ```bash
   npx lingo.dev@latest login
   ```

   这将打开您的默认浏览器并要求您进行身份验证。

3. 按照提示操作。

## 第 7 步：生成翻译

在包含 `i18n.json` 文件的目录中，运行以下命令：

```bash
npx lingo.dev@latest run
```

此命令将执行以下操作：

1. 读取 `i18n.json` 文件。
2. 查找需要翻译的文件。
3. 从文件中提取可翻译内容。
4. 使用配置的 LLM 翻译提取的内容。
5. 将翻译后的内容写回文件系统。

首次生成翻译时，会创建一个 `i18n.lock` 文件。此文件记录已翻译的内容，防止后续运行时不必要的重复翻译。

## 示例

### en/example.yml

```yaml
en:
  navigation:
    home: "Home"
    about: "About Us"
    contact: "Contact"
    services: "Services"
  forms:
    title: "Contact Form"
    name_label: "Your Name"
    email_label: "Email Address"
    message_label: "Message"
    submit_button: "Send Message"
    success_message: "Thank you for your message!"
```

### es/example.yml

```yaml
es:
  navigation:
    home: "Inicio"
    about: "Sobre Nosotros"
    contact: "Contacto"
    services: "Servicios"
  forms:
    title: "Formulario de Contacto"
    name_label: "Su Nombre"
    email_label: "Dirección de Correo Electrónico"
    message_label: "Mensaje"
    submit_button: "Enviar Mensaje"
    success_message: "¡Gracias por su mensaje!"
```

### i18n.json

```json
{
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "yaml-root-key": {
      "include": ["./[locale]/example.yml"]
    }
  },
  "$schema": "https://lingo.dev/schema/i18n.json"
}
```

### i18n.lock

```yml
version: 1
checksums:
  1b0d7c9f07dcc31a978bc337763270ea: {}
  87b1c33c3f85415e0906ece6cfed17c5:
    navigation/home: 104a3db3b671c04e167eafbe21e57881
    navigation/about: 8f89131a66d4659be07cd5af2c7ea898
    navigation/contact: 9afa39bc47019ee6dec6c74b6273967c
    navigation/services: 8ea10b45b9abab2a3bfc3c07e1c9cdc6
    forms/title: ac85dea7c7f0bf1cd7d48cc1b4da3acc
    forms/name_label: 03c6ae7996d5841f743cd406b4eff72d
    forms/email_label: 0ee22bbbe989a0c61a18023407d12dc2
    forms/message_label: f2f72126bd244cfc534eab395e054362
    forms/submit_button: 487177489aafc9c0243c57ef3850a2d9
    forms/success_message: a0a7aa980dffa31d4d194af718a917b3
```
