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 — это бесплатный инструмент с открытым исходным кодом для перевода приложений и контента с помощью ИИ. Он разработан для замены традиционного программного обеспечения для управления переводами, интегрируясь с существующими конвейерами.

Чтобы узнать больше, см. Обзор.

О данном руководстве

Это руководство объясняет, как переводить файлы YAML с помощью Lingo.dev CLI.

Вы узнаете, как:

Создать проект с нуля
Настроить конвейер перевода
Генерировать переводы с помощью ИИ

Предварительные требования

Для использования 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. Настройте исходную локаль

Исходная локаль — это оригинальный язык и регион, на которых был написан ваш контент. Чтобы настроить исходную локаль, установите свойство locale.source в файле i18n.json:

{
  "$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 добавьте объект "yaml" в объект buckets:

{
  "$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")
Рекурсивные шаблоны (например, **/*.yml) не поддерживаются.

Шаг 6. Настройка LLM

CLI Lingo.dev использует большие языковые модели (LLM) для перевода контента с помощью ИИ. Чтобы использовать одну из этих моделей, вам нужен API-ключ от поддерживаемого провайдера.

Чтобы начать как можно быстрее, мы рекомендуем использовать Lingo.dev Engine — нашу собственную платформу, которая предоставляет 10 000 токенов бесплатного ежемесячного использования:

Зарегистрируйтесь в 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