YAML - Lingo.dev CLI

什么是 YAML？

YAML（YAML Ain't Markup Language）是一种面向人类可读的数据序列化格式，常用于配置文件、数据交换和结构化数据存储。它通过缩进表示层级关系，并支持复杂的数据结构。

例如：

title: "MyApp"
description: Hello, world!
welcome_message: 'Welcome to MyApp'

user_profile:
  display_name: "John Doe"
  bio: Software developer

navigation_items:
  - "Home"
  - "About"
  - "Contact"

product:
  name: "MyWidget"
  tagline: The best widget ever

什么是 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" 对象：

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

在 "yaml" 对象中，定义一个或多个 include 模式的数组：
```
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "yaml": {
      "include": ["./[locale]/example.yml"]
    }
  }
}
```
这些模式定义了需要翻译的文件。

模式要求如下：
- 必须包含 [locale] 作为已配置语言环境的占位符
- 可以指向文件路径（如 "[locale]/config.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

title: "MyApp"
description: Hello, world!
welcome_message: 'Welcome to MyApp'

user_profile:
  display_name: "John Doe"
  bio: Software developer

navigation_items:
  - "Home"
  - "About"
  - "Contact"

product:
  name: "MyWidget"
  tagline: The best widget ever
  features:
    - "Easy to use"
    - "Fast and reliable"

settings:
  max_users: 100
  enabled: true
  timeout: 30.5

complex_structure:
  level_one:
    level_two:
      message: "Deep nested text"
locked_key_1: "This value is locked and should not be changed"
ignored_key_1: "This value is ignored and should not appear in target locales"

es/example.yml

title: "MyApp"
description: "¡Hola, mundo!"
welcome_message: "Bienvenido a MyApp"
user_profile:
  display_name: "Juan Pérez"
  bio: "Desarrollador de software"
navigation_items:
  - "Inicio"
  - "Acerca de"
  - "Contacto"
product:
  name: "MyWidget"
  tagline: "El mejor widget de todos"
  features:
    - "Fácil de usar"
    - "Rápido y confiable"
settings:
  max_users: 100
  enabled: true
  timeout: 30.5
complex_structure:
  level_one:
    level_two:
      message: "Texto anidado profundo"
locked_key_1: "This value is locked and should not be changed"

i18n.json

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

i18n.lock

version: 1
checksums:
  1b0d7c9f07dcc31a978bc337763270ea:
    title: 7dc70110429d46e3685f385bd2cc941c
    description: 0468579ef2fbc83c9d520c2f2f1c5059
    welcome_message: d1c3a9f35e377554a4ccaa467ca26614
    user_profile/display_name: febee8e9ab40b2fe5106d72675228d00
    user_profile/bio: 155ddcb7c93493ac72a37074eea0a653
    navigation_items/0: 104a3db3b671c04e167eafbe21e57881
    navigation_items/1: 944521eeeed2511833d2299931273c71
    navigation_items/2: 9afa39bc47019ee6dec6c74b6273967c
    product/name: ed21de171d538a49db999c47875f75a5
    product/tagline: b7ac41680e82d75ae7f5774f7ceef1b4
    product/features/0: c916ba887951a02793ff851853fd964f
    product/features/1: 1c60a04d6890c6ec910a7f2e6ec0ae7b
    complex_structure/level_one/level_two/message: b53034560bf657106e5aaea9160e357e