Конфигурация CLI

Задайте правила поиска исходных файлов, параметры перевода и пути к целевым файлам в .lingo/config.json.

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

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "locales/en.json" }]
}

Выполните link, чтобы добавить ИД организации и движка локализации для удалённого перевода. Для локального извлечения достаточно настроек i18n — эти ИД не нужны. Используйте строгий JSON: комментарии и запятые после последнего элемента не допускаются.

Корневые поля #

ПолеОписание
orgId, engineIdНепустые ИД ресурсов. Вместе задают удалённую привязку.
sourceLocaleНепустая строка с исходной локалью.
targetLocalesНепустые строки. При выполнении CLI удаляет дубликаты и точное совпадение с исходной локалью.
filesЗаписи об исходных файлах, описанные ниже.
i18n.messagesPathКаталог переводов для извлечения, проверки и очистки. По умолчанию — locales.
i18n.typesPathПуть к файлу объявлений для извлечения и проверки. По умолчанию — lingo.d.ts.
github.workflows.onPushToDefaultBranch.enabledНеобязательный триггер интеграции для ветки по умолчанию.
github.workflows.onPullRequest.enabledНеобязательный триггер интеграции для пул-реквеста.
github.safety.requireApprovalНеобязательная настройка подтверждения запуска интеграции.

CLI предупреждает о неизвестных ключах в корне и записях о файлах и игнорирует их. Из-за опечатки может сохраниться значение по умолчанию — вместо того чтобы весь файл был отклонён.

Команда init записывает настройки локализации, link — ИД привязки, а unlink удаляет только эти ИД. При записи остальные корневые разделы сохраняются, но init --force создаёт записи о файлах заново, и расширенные параметры теряются. Настройки GitHub не устанавливают приложение и не позволяют команде push из CLI запускать автоматизацию репозитория. Для этого настройте интеграцию.

Поля записи о файле #

ПолеОписание
patternОдин непустой шаблон исходных файлов.
includeШаблоны исходных файлов. Имеют приоритет над pattern, даже если список пуст.
excludeШаблоны для исключения файлов из этой записи.
formatЯвно заданный формат из списка поддерживаемых форматов ниже.
localeFormatПредставление локали в пути: bcp47, underscore или android.
targetPath, sourceRootШаблон выходного пути и необязательный префикс, удаляемый для [path].
translateFrontmatterFieldsПоля метаданных, которые выбирают обработчики форматов семейства Markdown.
translateComponentPropsИмена свойств или правила для свойств с фильтром по компонентам.
lockedKeys, preservedKeys, ignoredKeysНепустые массивы путей к ключам для обработчиков, которые их поддерживают.
injectLocaleЛогическое значение или { "enabled": true, "key": "language" }.
keyColumnТолько CSV: заголовок столбца ключей. По умолчанию — первая ячейка строки заголовков.
lockedPatternsТолько для Properties: регулярные выражения RE2 в значениях остаются без перевода.

В каждой записи нужен pattern или include. Пустой include ничего не выбирает. Параметры берутся из первой подходящей записи. В разделе Управление ключами описано, каким записям принадлежат значения и где проходят границы форматов.

Шаблоны файлов #

При сопоставлении * работает внутри сегмента пути, а **/ — на нескольких уровнях каталогов. Для рекурсивного поиска в поддереве используйте docs/en/**/*. Один лишь ** в конце работает иначе. Не рассчитывайте, что фигурные скобки и расширенные glob-шаблоны работают так же, как в другой библиотеке.

json
{
  "sourceLocale": "en",
  "targetLocales": ["de"],
  "files": [
    {
      "include": ["docs/en/**/*.md", "docs/en/**/*.mdx"],
      "exclude": ["docs/en/private/**/*"]
    }
  ]
}

Исключение действует только в своей записи. Другая запись всё равно может включить этот файл. Поиск пропускает .git и node_modules, но не всё содержимое .gitignore. Шаблоны, переданные команде push как позиционные аргументы, оставляют только совпадения с настроенными исходными файлами и меняют режим планирования. Заключайте их в кавычки в командной оболочке.

Выбор формата #

Настроены следующие форматы: json, jsonc, md, mdx, markdoc, yaml-openapi, po, flutter, xcode-strings, yaml, android, typescript, xcode-xcstrings, srt, xliff, xcode-stringsdict, php, yaml-root-key, html, txt, csv и properties.

СуффиксОпределяемый формат
.json, .jsoncJSON или JSONC.
.md, .mdx, .mdocMarkdown, MDX, Markdoc.
.html, .htmHTML.
.po, .arbGettext, Flutter.
.strings, .xcstrings, .stringsdictСоответствующий формат Apple.
.ts, .mts, .ctsTypeScript.
.srt, .xlf, .xliff, .phpSubRip, XLIFF, PHP.
.txtОбычный текст, только если шаблон заканчивается на .txt или задан формат txt.
.csvCSV, только если шаблон заканчивается на .csv или задан формат csv.
.propertiesJava properties — только для шаблона, который заканчивается на .properties или properties.
.yaml, .ymlЯвно задайте yaml, yaml-root-key или OpenAPI на основе yaml.
.xmlЯвно задайте android. Произвольный XML не поддерживается.

Точный идентификатор для OpenAPI — yaml-openapi. Даже при явном выборе формата поиск файлов ограничен списком поддерживаемых расширений. Файл .txt, .csv или .properties относится только к записи, в которой шаблон заканчивается на это расширение или указан соответствующий формат — txt, csv или properties. Такая запись выбирает только файлы с этим расширением. Файлы .js, .tsx, .pot, MJML и VTT не настроены как входные файлы CLI. Извлечение из React TSX выполняется отдельно.

При переводе HTML выбранный текст и атрибуты заменяются прямо в исходном коде. Остальная разметка, комментарии и форматирование сохраняются. Если элемент <html> задан явно, в его атрибут lang записывается целевая локаль. Фрагменты остаются фрагментами. Подробнее о выборе текста и формировании результата — в разделе HTML.

В разделе Форматы описана работа парсеров, в том числе пропускаемые структуры и ограничения восстановления. Общие серверные обработчики не расширяют этот набор форматов CLI.

Выходные пути #

Задайте явный шаблон, если пути исходных файлов не указывают их локаль:

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [
    {
      "pattern": "docs/**/*.md",
      "sourceRoot": "docs",
      "targetPath": "i18n/[locale]/docs/[path]"
    }
  ]
}

docs/start.md превращается в i18n/de/docs/start.md и i18n/fr/docs/start.md. [locale] использует представление локали из записи, а [path] удаляет корень исходных файлов с учётом границ сегментов пути. Корень docs не удаляет часть docsite.

В шаблонах обязателен [locale], а для входных glob-шаблонов также нужен [path]. Других подстановок нет. Абсолютные пути, .., корни с glob-шаблонами, корни вне входных путей и выходные файлы, которые поиск снова находит среди настроенных исходных файлов, отклоняются. sourceRoot без targetPath недопустим. Команда push также проверяет конфликты выходных путей без учёта регистра.

Команды push, pull и purge также проверяют фактическое расположение файлов. Если исходный файл, целевой файл, .lingo/lock.json или .lingo/config.json ведёт за пределы корня проекта или внутрь .git, например через символическую ссылку, команда завершается с ошибкой до чтения, записи или удаления по этому пути. Ссылки, которые ведут внутрь проекта, работают, но запись через целевой файл или Lockfile, если сам файл является ссылкой, не выполняется. В монорепозитории запускайте команду из корня, содержащего общие файлы, а не ссылайтесь на них из пакета.

Без шаблона CLI пробует определить путь по каталогу исходной локали, затем по полному имени файла без расширения, затем по структуре платформы. Если ничего не подошло, добавляет каталог локали и выдаёт предупреждение. Примеры: locales/en.json → locales/de.json, app_en.arb → app_de.arb, Base.lproj → целевой .lproj, а в Android values → ресурсы с квалификатором локали. Читайте предупреждения и проверяйте, что приложение загружает файлы из этого расположения.

XCStrings и CSV хранят все локали в исходном файле и не допускают targetPath. Результаты для нескольких локалей намеренно записываются в один файл. Его наличие не означает, что в нём есть каждая локаль. Команда purge пропускает общий файл, поэтому не может удалить отдельные записи локалей.

Как выбрать метаданные и текст компонентов #

При переводе форматов семейства Markdown, если параметр не задан, выбираются поля title и description в блоке метаданных. Пустой список отключает их перевод, а явный список выбирает другие поля. Для путей к вложенным скалярным значениям и массивам нужен блок метаданных, который удаётся разобрать. Если в нём ошибки, обработчик может перейти к поиску на верхнем уровне.

json
{
  "pattern": "docs/en/**/*.mdx",
  "translateFrontmatterFields": ["title", "description"],
  "translateComponentProps": ["aria-label", { "component": ["Card", "Callout"], "props": ["title"] }]
}

Строка выбирает свойство без фильтра по компонентам. Объект выбирает props и может ограничивать выбор именами компонентов. Эти правила выбирают для перевода текстовые литералы, а не код компонентов или все атрибуты. Markdown, MDX и Markdoc работают по-разному. При смене путей проверьте обработчик.

Чтобы добавить указания для перевода JSONC, поместите @context непосредственно перед нужной строкой. В обычном выводе JSONC сохраняются метки @orphan, но остальные комментарии удаляются. Поэтому для метаданных React @src следуйте правилам загрузки каталогов переводов, а не рассчитывайте, что pull их сохранит.

Для фреймворков документации выбирайте фактические каталоги исходных и выходных файлов отдельно от маршрутизации. OpenAPI использует yaml-openapi, корневые ключи локалей в стиле Rails — yaml-root-key, а обычный YAML — yaml. Одного совпадения расширения недостаточно, чтобы выбрать правильную обработку.

Локали #

Конфигурация проверяет, что строки непустые, а не сверяет их с исчерпывающим списком локалей. Используйте идентификаторы, нужные модели и приложению, в том числе с регионом или письменностью. localeFormat управляет путями: bcp47 сохраняет дефисы, underscore даёт pt_BR, а android — формы вроде pt-rBR или b+zh+Hans. Для формата Android используется представление Android, если не задано другое. Это также влияет на сопоставление исходных файлов.

Завершите обычные обновления исходных файлов, прежде чем добавлять целевую локаль и создавать недостающие файлы для неё. В разделе Как добавить язык объясняется, как такой порядок помогает поддерживать существующие языки в актуальном состоянии. Удаление целевой локали исключает её из дальнейшего выбора, но не удаляет существующие файлы. Для встроенных метаданных локали и общих каталогов переводов действуют правила их обработчика. Правильно записанный путь не гарантирует верное направление текста, маршрутизацию или качество перевода.

Пути к каталогам переводов #

При извлечении и проверке явно заданные --out/--types имеют приоритет над настройками i18n, а те — над значениями по умолчанию. Значение --source-locale по умолчанию — en, независимо от sourceLocale в настройках локализации. Изменение messagesPath не обновляет files[]. Для перевода выберите путь к сгенерированному JSONC.

Монорепозитории #

Корневая конфигурация позволяет использовать общие локали и движок локализации для пакетов, пути к которым заданы рекурсивно или явно. Отдельные конфигурации пакетов позволяют хранить локали, настройки и Lockfile независимо друг от друга. Запускайте команду из корня нужного пакета, чтобы поиск ближайшей конфигурации не выбрал конфигурацию родительского каталога вместо нужной.

Матрица каталогов CI должна сохранять собранные выходные файлы каждого проекта и исключать одновременную запись в одни и те же файлы. Локальные указатели запусков в домашнем каталоге зависят от абсолютных корневых путей и не передаются через Lockfile. lingo check сравнивает все исходные файлы, выбранные через files, с Lockfile на уровне файлов. Ключи внутри них не проверяются.

Конфигурация оценки #

lingo score использует исполняемый файл lingo.config.ts, который загружается через Jiti. Эта конфигурация отделена от JSON-конфигурации проекта и не регистрирует произвольные локальные загрузчики форматов. Не смешивайте доверенные плагины оценки с настройками удалённой локализации файлов.