JSON5 - Lingo.dev CLI

Что такое JSON5?

JSON5 — это расширение JSON, которое упрощает написание и поддержку вручную. Оно поддерживает комментарии, некавыченные ключи, завершающие запятые и более гибкий синтаксис, оставаясь совместимым с JavaScript.

Например:

{
  // JSON5 поддерживает комментарии!
  title: "Привет, мир!",
  description: "Простое демонстрационное приложение с функциями JSON5",

  // Некавыченные ключи разрешены
  author: {
    name: "John Doe",
  },

  messages: ["Добро пожаловать в MyApp", "Привет, мир!"],

  // Разрешены завершающие запятые
  locked_key_1: "Это значение заблокировано и не должно изменяться",
}

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

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

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

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

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

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

Шаг 5. Создание корзины

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

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

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

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

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

{
  // JSON5 поддерживает комментарии!
  title: "Привет, мир!",
  description: "Простое демонстрационное приложение с функциями JSON5",
  version: "1.0.0",
  support_email: "[email protected]",
  homepage: "https://lingo.dev",
  deprecated: null,
  empty: "",
  emoji: "🚀",

  // Некавыченные ключи разрешены
  author: {
    name: "John Doe",
  },

  contributors: [{ name: "Alice" }, { name: "Bob" }],

  messages: ["Добро пожаловать в MyApp", "Привет, мир!"],

  config: {
    theme: {
      primary: "Синяя тема",
    },
  },

  mixed_array: [
    "Смешанный контент здесь",
    42,
    true,
    {
      nested_message: "Вложенный текст",
    },
  ],

  // Шестнадцатеричные числа работают в JSON5
  hex_value: 0xdeadbeef,

  // Разрешены завершающие запятые
  locked_key_1: "Это значение заблокировано и не должно изменяться",
}

es/example.json5

{
  // JSON5 поддерживает комментарии!
  title: "Привет, мир!",
  description: "Простое демонстрационное приложение с функциями JSON5",
  version: "1.0.0",
  support_email: "[email protected]",
  homepage: "https://lingo.dev",
  deprecated: null,
  empty: "",
  emoji: "🚀",

  // Некавыченные ключи разрешены
  author: {
    name: "Хуан Перес",
  },

  contributors: [{ name: "Алисия" }, { name: "Роберто" }],

  messages: ["Добро пожаловать в MyApp", "Привет, мир!"],

  config: {
    theme: {
      primary: "Синяя тема",
    },
  },

  mixed_array: [
    "Смешанное содержимое здесь",
    42,
    true,
    {
      nested_message: "Вложенный текст",
    },
  ],

  // Шестнадцатеричные числа работают в JSON5
  hex_value: 0xdeadbeef,

  // Разрешены завершающие запятые
  locked_key_1: "Это значение заблокировано и не должно изменяться",
}

i18n.json

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

i18n.lock

version: 1
checksums:
  455da9346f4e772000927cd2ff5bb898:
    title: 0468579ef2fbc83c9d520c2f2f1c5059
    description: 6f4922f45568161a8cdf4ad2299f6d23
    version: 54a9e730e88fb16291b852274d433923
    support_email: 10627fcc465897af0f5e1bba042685f9
    emoji: b328c432cee108a87a92f05258b6a651
    author/name: febee8e9ab40b2fe5106d72675228d00
    contributors/0/name: e80d4063a32adaad7b0a82b0bcc10551
    contributors/1/name: b2bca2fa3c890618e56d07473f26ead3
    messages/0: d1c3a9f35e377554a4ccaa467ca26614
    messages/1: 0468579ef2fbc83c9d520c2f2f1c5059
    config/theme/primary: 7535a3779d6934ea8ecf18f5cb5b93fd
    mixed_array/0: 001b5b003d96c133534f5907abffdf77
    mixed_array/3/nested_message: 5f0782dfc5993e99890c0475bc295a30
    hex_value: a1b2c3d4e5f6789012345678abcdef01