Конфигурация 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.8
}

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

  • $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 также поддерживает платформенно-специфичные форматы локалей, такие как en-rUS для Android-директорий ресурсов. Чтобы получить полный список поддерживаемых кодов локалей, выполните:

npx lingo.dev@latest show locale sources  # Доступные исходные языки
npx lingo.dev@latest show locale targets  # Доступные целевые языки

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

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

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

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

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

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

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

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Ваш пользовательский запрос на перевод с заполнителями {source} и {target}"
  }
}

Для использования движка Lingo.dev:

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

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

  • 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 — Массив ключей, в которые автоматически должен быть внедрён код локали.

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

Шаблоны включения используют синтаксис, похожий на glob, со специальным заполнителем [locale]:

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

Шаблоны исключения предотвращают обработку определённых файлов в рамках шаблонов включения.

Расширенные параметры шаблона

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

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

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

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

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

Поддерживаемые типы хранилищ

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

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

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

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

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

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

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "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. Обновляет поле версии в соответствии с текущей схемой

Поведение миграции:

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

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