Конфигурация i18n.json

i18n.json — это стандартный конфигурационный файл, который управляет работой Lingo.dev CLI и интеграций Lingo.dev CI/CD.

i18n.json использует схему для конфигурации, разделяя языковые настройки, шаблоны поиска файлов и параметры AI-движка перевода на отдельные секции. Благодаря этому разработчики могут сразу понять, как устроен их процесс локализации, просто посмотрев на конфиг.

В этом гайде предполагается, что у тебя уже установлен Lingo.dev CLI и ты настраиваешь процесс перевода. После прочтения ты разберёшься в структуре i18n.json, его опциях и поймёшь, как каждая секция влияет на поведение перевода.

Версия

Поле version указывает версию схемы конфигурации:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10"
}

Элементы конфигурации:

  • $schema — Ссылка на определение схемы JSON для автодополнения и валидации в IDE. Схема помогает заранее находить ошибки в конфиге благодаря встроенной документации и проверке типов.
  • version — Версия схемы конфигурации для совместимости при миграциях.

Lingo.dev CLI использует это поле для автоматической миграции конфига при выходе новых версий схемы.

Языковая конфигурация

Секция locale определяет, с какими языками работает Lingo.dev CLI:

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja", "de"]
  }
}

Коды языков соответствуют стандарту BCP 47, который включает коды из ISO 639 и, при необходимости, региональные коды из ISO 3166-1. Примеры: en, en-US, es-ES и zh-Hans.

Lingo.dev CLI также поддерживает платформенные форматы локалей, например, android-стиль en-rUS для директорий ресурсов. Чтобы получить полный список поддерживаемых кодов локалей, выполни команду:

npx lingo.dev@latest show locale sources  # Available source languages
npx lingo.dev@latest show locale targets  # Available target languages

Если нужного кода локали нет, просто создай pull request, чтобы его добавить!

Элементы конфигурации:

  • locale.source — Код исходного языка, который определяет, в каких файлах находится оригинальный контент. Все переводы идут от исходного к целевым.
  • locale.targets — Массив кодов целевых языков для твоих рынков. Каждый код — это отдельный файл или секция в файле, в зависимости от формата.

Команды для проверки языка:

Конфигурация провайдера

Раздел provider определяет, какой AI-сервис перевода использует Lingo.dev CLI. Этот раздел необязателен: если его нет, по умолчанию используется AI-движок перевода Lingo.dev.

Для прямого доступа к LLM API:

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Your custom translation prompt with {source} and {target} placeholders"
  }
}

Для Lingo.dev Engine:

Чтобы использовать Lingo.dev Engine, просто не указывайте раздел provider. Движок сам подбирает модели и промпты на основе оптимизаций и ваших настроек Lingo.dev Engine.

Элементы конфигурации:

  • provider.id — идентификатор AI-сервиса перевода (например, "openai" или "anthropic").
  • provider.model — название AI-модели перевода (например, "gpt-4o-mini" для OpenAI или "claude-3-haiku" для Anthropic).
  • provider.prompt — системный промпт, который управляет поведением перевода. Плейсхолдеры {source} и {target} заменяются на реальные коды языков во время выполнения.

Конфигурация бакетов

Бакеты определяют шаблоны поиска файлов и правила обработки. Каждый бакет — это определённый формат файла с индивидуальными шаблонами включения и исключения.

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json", "app/[locale]/*.json"],
      "exclude": ["locales/[locale]/internal.json"],
      "lockedKeys": ["app/version", "config/apiUrl"],
      "injectLocale": ["settings/language"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"],
      "exclude": ["docs/[locale]/drafts/*.md"]
    }
  }
}

Элементы конфигурации:

  • buckets.[bucket-type] — группа настроек для конкретного бакета файлового формата.
    • buckets.[bucket-type].include — массив шаблонов поиска файлов. Может содержать строки или объекты.
      • buckets.[bucket-type].include.[string] — простой шаблон пути к файлу с плейсхолдером [locale].
      • buckets.[bucket-type].include.[object] — расширенная конфигурация шаблона с такими свойствами:
        • path — шаблон пути к файлу с плейсхолдером [locale].
        • delimiter — разделитель для кодов локалей. По умолчанию - (дефис), можно поменять на _ (нижнее подчёркивание). Переопределяет разделитель из конфигурации локали.
    • buckets.[bucket-type].exclude — массив шаблонов исключения файлов, которые не нужно обрабатывать.
    • buckets.[bucket-type].lockedKeys — массив ключей, которые не должны переводиться. Использует слэш / как разделитель для вложенных ключей. Для совпадения с несколькими ключами используйте звёздочку *.
    • buckets.[bucket-type].ignoredKeys — массив ключей, которые нужно игнорировать при переводе. Использует слэш / как разделитель для вложенных ключей. Для совпадения с несколькими ключами используйте звёздочку *.
    • buckets.[bucket-type].injectLocale — массив ключей, куда код локали будет автоматически подставляться. Использует слэш / как разделитель для вложенных ключей. Для совпадения с несколькими ключами используйте звёздочку *.

Базовая структура шаблона

Include-шаблоны используют синтаксис, похожий на glob, со специальным плейсхолдером [locale]:

  • locales/[locale].json → locales/en.json, locales/es.json
  • docs/[locale]/*.md → docs/en/*.md, docs/es/*.md

Exclude-шаблоны исключают обработку определённых файлов внутри include-шаблонов.

Расширенные опции шаблонов

Пользовательские разделители локалей для разных форматов имён файлов:

{
  "include": [
    "standard/[locale].json",
    {
      "path": "underscore/[locale].json",
      "delimiter": "_"
    }
  ]
}

Доступные разделители:

  • - (дефис): en-US.json
  • _ (подчёркивание): en_US.json

Совет: этот параметр управляет разделителем, который используется в имени файла, так что можно использовать его в монорепозитории, где у разных проектов свои правила разделителей.

Поддерживаемые типы бакетов

Lingo.dev CLI поддерживает следующие типы бакетов для разных форматов файлов:

  • android — ресурсы Android XML
  • csv — CSV-файлы с отдельными файлами для каждого языка
  • flutter — Flutter ARB-файлы
  • html — HTML-файлы с отдельными файлами для каждого языка
  • json — JSON-файлы с отдельными файлами для каждого языка
  • markdown — Markdown-файлы с отдельными файлами для каждого языка
  • mdx — MDX-файлы с отдельными файлами для каждого языка
  • xcode-strings — устаревшие Xcode .strings-файлы
  • xcode-stringsdict — Xcode .stringsdict-файлы для плюрализации
  • xcode-xcstrings — Xcode strings catalog-файлы
  • yaml — YAML-файлы с отдельными файлами для каждого языка
  • yaml-root-key — YAML-файлы с корневыми ключами по локали
  • properties — Java .properties-файлы
  • po — GNU gettext .po-файлы
  • xml — универсальные XML-файлы с отдельными файлами для каждого языка
  • php — PHP array-файлы
  • vue-json — Vue.js i18n JSON-файлы
  • typescript — TypeScript-файлы с отдельными файлами для каждого языка

Примеры конфигураций

Базовая конфигурация

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

Конфигурация монорепозитория

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en-US",
    "targets": ["es-ES", "fr-FR"]
  },
  "buckets": {
    "json": {
      "include": ["apps/web/locales/[locale].json"]
    },
    "mdx": {
      "include": ["packages/docs/content/[locale]/*.mdx"]
    },
    "xcode-xcstrings": {
      "include": ["ios/Localizable.xcstrings"]
    },
    "android": {
      "include": ["android/values-[locale]/strings.xml"]
    }
  }
}

Миграция версий

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

Когда Lingo.dev CLI обнаруживает устаревшую версию конфигурации, он:

  1. Создаёт резервную копию вашего текущего файла i18n.json
  2. Мигрирует конфигурацию на последнюю версию схемы
  3. Сохраняет все настройки, включая кастомных провайдеров, конфигурации bucket и заблокированные ключи
  4. Обновляет поле version в соответствии с текущей схемой

Как работает миграция:

Миграция запускается автоматически при любой операции CLI, которая читает файл конфигурации. Никаких ручных действий не требуется, и ваш процесс перевода продолжается без перебоев.

Эта система миграции гарантирует, что конфигурации i18n.json всегда совместимы с обновлениями Lingo.dev CLI, при этом сохраняется обратная совместимость с существующими проектами.