HTML

AI-перевод HTML-файлов с помощью Lingo.dev CLI

Что такое HTML?

HTML (HyperText Markup Language) — это стандартный язык разметки для создания веб-страниц и веб-приложений. Он использует теги для структурирования контента и определения таких элементов, как заголовки, абзацы, ссылки, изображения и формы.

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

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

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

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

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

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

Для HTML-файлов переводимым контентом считается:

  • Текст внутри HTML-элементов
  • Значения атрибутов, включая:
    • атрибуты alt (описания изображений)
    • атрибуты title (подсказки)
    • атрибуты placeholder (подписи к полям ввода)
    • атрибуты value (значения кнопок и полей ввода)
    • атрибуты meta-тегов content
  • Атрибут lang автоматически обновляется в соответствии с целевой локалью

Теги script, style и непереводимые атрибуты сохраняются.

Например:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>MyApp - Hello World</title>
    <meta name="description" content="A simple demo app" />
  </head>
  <body>
    <h1>Welcome to MyApp</h1>
    <p>Hello, world! This is a simple demo with <strong>bold text</strong>.</p>
    <img src="example.jpg" alt="Example image" />
  </body>
</html>

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

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

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

  2. В объекте "html" определите массив из одного или нескольких паттернов include:

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

    Эти паттерны определяют, какие файлы переводить.

    Сами паттерны:

    • должны содержать [locale] как плейсхолдер для выбранной локали
    • могут указывать на пути к файлам (например, "[locale]/config.html")
    • могут использовать звёздочки как подстановочные знаки (например, "[locale]/*.html")

    Рекурсивные glob-паттерны (например, **/*.html) не поддерживаются.

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

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

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

  1. Зарегистрируйтесь в Lingo.dev.

  2. Выполните следующую команду:

    npx lingo.dev@latest login

    Откроется ваш браузер по умолчанию и появится запрос на аутентификацию.

  3. Следуйте инструкциям на экране.

Шаг 7. Генерация переводов

В каталоге, где находится файл i18n.json, выполните следующую команду:

npx lingo.dev@latest run

Эта команда:

  1. Считывает файл i18n.json.
  2. Находит файлы, которые нужно перевести.
  3. Извлекает переводимый контент из файлов.
  4. Использует настроенную LLM для перевода извлечённого контента.
  5. Записывает переведённый контент обратно в файловую систему.

При первой генерации переводов создаётся файл i18n.lock. В нём хранится информация о том, что уже переведено, чтобы избежать лишних повторных переводов при следующих запусках.

Пример

en/example.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>MyApp - Hello World</title>
    <meta name="description" content="A simple demo app" />
  </head>
  <body>
    <h1>Welcome to MyApp</h1>
    <p>Hello, world! This is a simple demo with <strong>bold text</strong>.</p>
    <img src="example.jpg" alt="Example image" />
    <input type="text" placeholder="Enter text here" />
    <a href="#" title="Click for more">Learn more</a>
  </body>
</html>

es/example.html

<!DOCTYPE html>
<html lang="es">
  <head>
    <title>MyApp - Hola Mundo</title>
    <meta name="description" content="Una aplicación de demostración simple" />
  </head>
  <body>
    <h1>Bienvenido a MyApp</h1>
    <p>¡Hola, mundo! Esta es una demostración simple con <strong>texto en negrita</strong>.</p>
    <img src="example.jpg" alt="Imagen de ejemplo" />
    <input type="text" placeholder="Ingresa texto aquí" />
    <a href="#" title="Haz clic para más">Saber más</a>
  </body>
</html>

i18n.json

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

i18n.lock

version: 1
checksums:
  ab95e8c959a889717f02a05af5c5b1e6:
    head/0/0: 7d39787547365ee4194f29f3f54e5c05
    head/1#content: 49f8864eb0e53903f04532bf33e1e4fa
    head/2#content: c2a1da93efb7e744d100df705e5fcbfd
    head/3#content: d94b318cb327f61f1aea44a6cb1fdcad
    body/0/0: d1c3a9f35e377554a4ccaa467ca26614
    body/1/0: e19afd1952881bdf10063f9478980147
    body/1/1/0: 7cd9256312384858ecba6c29d3c2e550
    body/1/2: ce8b9bb44f031705708a70e068bb73c8
    body/1/3/0: 037d114f19b882f08994712b8d9c1e37
    body/1/4: f05f450fffcb17520c441ab9789f40ce
    body/2/0/0/0: 57d373bcffe2d376cbf9919da30ca30b
    body/3#alt: 68f95fca639f8bf72a4796b6734b02d5
    body/4#alt: cb7d920c3bbcade1c8e0307093f58573
    body/5#placeholder: a05ce3b4578f55e41bd2ad4964f966b4
    body/6#placeholder: a4554ed67c02872e302b0042724f859d
    body/7#title: c903c6985a40ce02d65c90229de35a4e
    body/7/0: e598091d132f890c37a6d4ed94f6d794
    body/8#title: d656021ba5f485fa1a82f8aac6ecc5de
    body/8/0: 1c6856488bd34ad87fcacce2d8e66a0b
    body/9/0: 862964e6cd73cdffdcac622406c6bac9