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

i18n.json — файл конфигурации, который управляет CLI Lingo.dev и интеграциями CI/CD. Он задаёт, какие языки переводить, где находится переводимый контент и какой backend перевода использовать.

Минимальный пример#

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

Поле $schema включает автодополнение и валидацию в IDE. Поле version отслеживает версию схемы для совместимости с автоматическими миграциями.

Локаль#

Раздел locale задаёт исходный и целевые языки:

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

Коды языков соответствуют стандарту BCP 47 — поддерживаются en, en-US, es-ES, zh-Hans, а также платформенные форматы, например Android-формат en-rUS.

Чтобы вывести список доступных кодов локалей:

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

Buckets#

Buckets задают шаблоны поиска файлов и правила обработки. Каждый ключ bucket определяет формат файла, а его значение настраивает, какие файлы включать или исключать:

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "exclude": ["locales/[locale]/internal.json"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  }
}

Шаблоны включения#

В шаблонах включения используется плейсхолдер [locale], который во время выполнения заменяется на настроенные коды локалей:

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

Пользовательские разделители локалей#

По умолчанию коды локалей в именах файлов используют дефис (-) в качестве разделителя: en-US.json. Чтобы использовать подчёркивания, передайте объект с полем delimiter:

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

В результате получится legacy/en_US.json вместо legacy/en-US.json.

Нотация путей ключей#

Массивы lockedKeys, ignoredKeys и preservedKeys используют запись с прямой косой чертой (/) для вложенных ключей и звёздочкой (*) для wildcard-шаблонов:

{
  "lockedKeys": ["brand/name", "config/*"]
}

Полный список поддерживаемых типов bucket см. в разделе Поддерживаемые форматы.

Провайдер#

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

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Translate the provided text from {source} to {target}."
  }
}

Подключение движка#

Чтобы направлять переводы через определённый движок локализации, добавьте поле engineId:

{
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

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

Полное руководство по настройке см. в разделе Подключите свой движок.

Переменные окружения#

Полный пример#

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name", "brand/tagline"],
      "ignoredKeys": ["internal/*"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  },
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

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

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

Следующие шаги#