带有根键的 YAML - Lingo.dev CLI

什么是带有根键的 YAML？

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

例如：

en:
  navigation:
    home: "Home"
    about: "About Us"
    contact: "Contact"
  forms:
    title: "Contact Form"
    name_label: "Your Name"
    submit_button: "Send Message"

什么是 Lingo.dev CLI？

Lingo.dev CLI 是一个免费、开源的命令行工具，可通过 AI 翻译应用和内容。它旨在替代传统的翻译管理软件，并可集成到现有的开发流水线中。

了解更多信息，请参见概述。

关于本指南

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

你将学习如何：

从零创建项目
配置翻译流水线
使用 AI 生成翻译

前置条件

要使用 Lingo.dev CLI，请确保已安装 Node.js v18 及以上版本：

❯ node -v
v22.17.0

第 1 步：设置项目

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

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

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

了解更多可用属性，请参见 i18n.json。

第 2 步：配置源语言环境

源语言环境 是指你的内容最初编写时所用的语言和地区。要配置源语言环境，请在 i18n.json 文件中设置 locale.source 属性：

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

源语言环境必须以 BCP 47 语言标签的形式提供。

有关 Lingo.dev CLI 支持的所有语言环境代码的完整列表，请参见支持的语言环境代码。

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

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

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

第 4 步：创建源内容

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

第 5 步：创建 bucket

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

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

在 "yaml-root-key" 对象中，定义一个或多个 include 模式的数组：
```
{
  "$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 个 token：

注册 Lingo.dev 账号。
运行以下命令：
```
npx lingo.dev@latest login
```
这将会打开您的默认浏览器，并要求您进行身份验证。
按照提示操作。

步骤 7. 生成翻译内容

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

npx lingo.dev@latest run

该命令将：

读取 i18n.json 文件。
查找需要翻译的文件。
提取文件中的可翻译内容。
使用已配置的 LLM 翻译提取的内容。
将翻译后的内容写回文件系统。

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

示例

en/example.yml

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

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

{
  "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

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