Конфигурация CLI
Задайте правила поиска исходных файлов, параметры перевода и пути к целевым файлам в .lingo/config.json.
.lingo/config.json задаёт, какие файлы проекта переводить и куда сохранять переводы. CLI ищет ближайший файл конфигурации вверх по дереву от рабочего каталога и отсчитывает пути проекта от найденного корня. Если конфигурации нет, локальные команды для каталогов переводов используют текущий рабочий каталог.
{
"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-шаблоны работают так же, как в другой библиотеке.
{
"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, .jsonc | JSON или JSONC. |
.md, .mdx, .mdoc | Markdown, MDX, Markdoc. |
.html, .htm | HTML. |
.po, .arb | Gettext, Flutter. |
.strings, .xcstrings, .stringsdict | Соответствующий формат Apple. |
.ts, .mts, .cts | TypeScript. |
.srt, .xlf, .xliff, .php | SubRip, XLIFF, PHP. |
.txt | Обычный текст, только если шаблон заканчивается на .txt или задан формат txt. |
.csv | CSV, только если шаблон заканчивается на .csv или задан формат csv. |
.properties | Java 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.
Выходные пути #
Задайте явный шаблон, если пути исходных файлов не указывают их локаль:
{
"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 в блоке метаданных. Пустой список отключает их перевод, а явный список выбирает другие поля. Для путей к вложенным скалярным значениям и массивам нужен блок метаданных, который удаётся разобрать. Если в нём ошибки, обработчик может перейти к поиску на верхнем уровне.
{
"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-конфигурации проекта и не регистрирует произвольные локальные загрузчики форматов. Не смешивайте доверенные плагины оценки с настройками удалённой локализации файлов.