MDX

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

Что такое MDX?

MDX — это формат, который объединяет Markdown с JSX, позволяя использовать React-компоненты прямо в вашем Markdown-контенте. Он часто используется для сайтов с документацией и контентно-насыщенных веб-приложений.

Например:


---

title: "Обзор ресторана: Bella Vista"
description: "Наш опыт ужина в новом итальянском ресторане в центре города"
author: "not-localized-author"

---

# Ужин в Bella Vista

Мы наконец-то посетили новый итальянский ресторан, который открылся в прошлом месяце на Главной улице.

## Атмосфера

Ресторан имеет теплую, уютную атмосферу с:

- **Приглушенным освещением**, создающим интимную обстановку
- *Легкой джазовой музыкой*, играющей на фоне

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

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

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

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

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

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

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

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

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

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

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

    Эти шаблоны определяют, какие файлы нужно перевести.

    Сами шаблоны:

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

    Рекурсивные шаблоны с глобами (например, **/*.mdx) не поддерживаются.

Шаг 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.mdx


---

title: "Обзор ресторана: Bella Vista"
description: "Наш опыт посещения нового итальянского ресторана в центре города"
author: "not-localized-author"
published: "2024-03-15"
rating: 4.5
locked_key_1: "Это значение должно оставаться неизменным во всех локалях"
ignored_key_1: "Это поле не должно появляться в целевых локалях"

---

# Ужин в Bella Vista

Мы наконец-то попробовали новый итальянский ресторан, который открылся в прошлом месяце на Main Street. Вот наш честный отзыв.

## Атмосфера

В ресторане царит тёплая, уютная атмосфера с:

- **Приглушённым освещением**, создающим интимную обстановку
- *Лёгкой джазовой музыкой* на фоне
- Свежими цветами на каждом столе

es/example.mdx


---

title: "Reseña de Restaurante: Bella Vista"
description: "Nuestra experiencia gastronómica en el nuevo restaurante italiano del centro"
author: "not-localized-author"
published: "2024-03-15"
rating: 4.5
locked_key_1: "This value should remain unchanged in all locales"

---

# Ужин в Bella Vista

Наконец-то мы посетили новый итальянский ресторан, который открылся в прошлом месяце на Main Street. Вот наш честный отзыв.

## Атмосфера

В ресторане царит тёплая, уютная атмосфера с:

- **Приглушённым освещением**, создающим интимную обстановку
- *Лёгкой джазовой музыкой* на фоне
- Свежими цветами на каждом столе

i18n.json

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

i18n.lock

version: 1
checksums:
  0d5b5aa6d2b9937d47fd63868ef9e9f6:
    meta/title: a4bdd0dee24f8318f3300dcae130a353
    meta/description: 609213841f122e494f62262618ee4761
    meta/author: f3f7164b5963b4da6cd31a2ec0251630
    content/0: 8a8520492d23503da5691602e60bd22a
    content/1: 1fc859854cda505b2a94a04c8b09ab43
    content/2: 8add667f2a1d5d791a64b50bde54fa59
    content/3: e6e34c4c92eda512ec209266abe8e074
    content/4: 07f1896ad050b9606d7674f70d847818
    content/5: bd4d40a4f0cc92ac8a880c8d9ce8b43d
    content/6: 3036a07a887121ea080427d84fc80912
    content/7: f555318416c5c5388c1d961ef02f5955
    content/8: 90e02688ab103de60e42c70ece7efc4d
    content/9: 8c5be3cd002a3a194c991821e0182e08
    content/10: 3495801a7461ac5ea8d78369873a5409
    content/11: d444739ce3d48afb7976067c67149a9e
    content/12: 5f02c0a3b6385f80bdd08cf7e2d8c04d
    content/13: 0a15fd446b87d907f58c303aece0882b
    content/14: 778ed0aa1f81768280a23afe559c55f7
    content/15: fa244af2d8e558d6c3644ff8c1a64562
    content/16: 14f593e7cf3b3df84a21e17db318912e
    content/17: 5f42d26a42aa29be063019eea27ad07c
    content/18: 48bb7e89e72d68d6de12f5cdac64fc18
    content/19: 1639b9ef57bf363e04293e27d1c13952
    content/20: bb1c8d22064f7af4879c69d444e6e769
    content/21: 52f9d6beaa85591f77811e1162d756c4