XML - Lingo.dev CLI

Что такое XML?

XML (Extensible Markup Language) — это язык разметки, который определяет правила кодирования документов в формате, удобном как для людей, так и для машин. Обычно используется для конфигурационных файлов, обмена данными и структурированного контента.

Например:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <title>Hello, world!</title>

  <description>
    <summary>Simple demo app</summary>
    <details>Basic example content</details>
  </description>

  <image src="photo.jpg" alt="Example photo" title="Click to view"/>

  <link href="example.com" label="Click here">Learn more</link>

  <message>
    <greeting>Hello there!</greeting>
    <body>Welcome to the app</body>
  </message>
</root>

Что такое Lingo.dev CLI?

Lingo.dev CLI — это бесплатный open-source CLI для перевода приложений и контента с помощью ИИ. Он создан, чтобы заменить традиционные системы управления переводами и легко интегрируется в существующие пайплайны.

Подробнее см. в разделе Обзор.

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

В этом гайде рассказывается, как переводить XML-файлы с помощью 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. Создайте исходный контент

Если вы ещё не сделали этого, создайте один или несколько XML-файлов с контентом для перевода. Эти файлы должны находиться по пути, который содержит исходную локаль (например, в названии папки как en/ или в имени файла как messages.en.xml).

Шаг 5. Создайте bucket

В файле i18n.json добавьте объект "xml" в объект buckets:

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

В объекте "xml" определите массив из одного или нескольких шаблонов include:
```
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "xml": {
      "include": ["./[locale]/example.xml"]
    }
  }
}
```
Эти шаблоны определяют, какие файлы переводить.

Сами шаблоны:
- должны содержать [locale] как плейсхолдер для выбранной локали
- могут указывать на пути к файлам (например, "[locale]/config.xml")
- могут использовать звёздочки как подстановочные знаки (например, "[locale]/*.xml")
Рекурсивные glob-шаблоны (например, **/*.xml) не поддерживаются.

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

Lingo.dev CLI использует большие языковые модели (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.xml

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <title>Hello, world!</title>

  <description>
    <summary>Simple demo app</summary>
    <details>Basic example content</details>
  </description>

  <image src="photo.jpg" alt="Example photo" title="Click to view"/>

  <link href="example.com" label="Click here">Learn more</link>

  <button type="submit" value="Submit" placeholder="Enter text">Submit</button>

  <message>
    <greeting>Hello there!</greeting>
    <body>Welcome to the app</body>
    <signature>Thanks, MyApp Team</signature>
  </message>
</root>

es/example.xml

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <title>¡Hola, mundo!</title>

  <description>
    <summary>Aplicación de demostración simple</summary>
    <details>Contenido de ejemplo básico</details>
  </description>

  <image src="photo.jpg" alt="Foto de ejemplo" title="Haz clic para ver"/>

  <link href="example.com" label="Haz clic aquí">Aprender más</link>

  <button type="submit" value="Enviar" placeholder="Ingresa texto">Enviar</button>

  <message>
    <greeting>¡Hola!</greeting>
    <body>Bienvenido a la aplicación</body>
    <signature>Gracias, Equipo de MyApp</signature>
  </message>
</root>

i18n.json

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

i18n.lock

version: 1
checksums:
  ec06a6ebae97ffd5f7afc99d9a8f051b:
    root/title: 0468579ef2fbc83c9d520c2f2f1c5059
    root/description/summary: f2c85bf6eeebeea33609e04598201bb6
    root/description/details: 2ee85b8f2f0f1bc008d9cf1f916cb09c
    root/image/%24/src: 3ce26f0a5486adf10e1b7eee1b866a70
    root/image/%24/alt: 94058fbed56fffaef2e9bbea59ba4a54
    root/image/%24/title: 60487c71b570d9dedca6fddd4a75d16a
    root/link/_: e598091d132f890c37a6d4ed94f6d794
    root/link/%24/href: 285d79d2783cf0769ab9e767362c1499
    root/link/%24/label: 26ce69aad587f70d47e7606436bf1d6d
    root/button/_: 7c91ef5f747eea9f77a9c4f23e19fb2e
    root/button/%24/type: fa8748b22d5bac98fdcd57e3d6594cf3
    root/button/%24/value: 7c91ef5f747eea9f77a9c4f23e19fb2e
    root/button/%24/placeholder: 7b5d59cee6952db66043a4b289b51884
    root/section/article/paragraph/sentence: 28ca53c71a2e3e3de79c892a9b193b1a
    root/meta/%24/name: d097029e873a4b19132e2603bd2c9fe4
    root/meta/%24/content: 0811ae3ab84aa87205383c3d8ac42bf3
    root/message/greeting: 85559fc839c5181b7958654e62c987d5
    root/message/body: ed0d4b1cde20d045f9f8c5007c784b0b
    root/message/signature: 181c8c304980949e101865098f548705