Lingo check

Завершайте CI с ошибкой, если переводы устарели, и проверяйте каталоги React.

lingo check завершается с ошибкой, если переводы устарели. Команда сравнивает каждый исходный файл с .lingo/lock.json, проверяет наличие всех целевых файлов, а в проектах @lingo.dev/react — ещё и извлечённые каталоги, объявления, контекст и переводы.

sh
lingo check --json

Какие проверки запускаются #

ПроверкаКогда выполняется
Проверка файловВ .lingo/config.json есть files или проект не использует React.
Проверки ReactВ корневом package.json или в ближайшем к --src указаны @lingo.dev/react, @lingo.dev/react-next или @lingo.dev/react-tanstack либо существует сгенерированный файл объявлений (по умолчанию lingo.d.ts).

В проекте React с files выполняются обе проверки. Если ни один шаблон files не соответствует файлу, проверка завершается с ошибкой no-source-files, как и lingo push. Исключение — проект React: в нём выполняются только проверки React, о чём сообщается в stderr. В проекте без files и без React команда завершается с той же ошибкой конфигурации, что и lingo push.

lingo check не требует ключа API и ничего не записывает. Команда не обращается к сети, кроме отправки телеметрии CLI, которую отключает DO_NOT_TRACK=1. Она возвращает код 1, если сообщает о проблеме или обнаруживает ошибку конфигурации (например, конфликт целевых путей или повреждённый Lockfile), и 0 в остальных случаях.

Проверка файлов #

Исходные файлы — те, которые отправила бы команда lingo push. Целевые пути — те, по которым команда push записала бы файлы для каждой настроенной целевой локали.

СитуацияПроблемаКак исправить
Исходный файл соответствует записи в Lockfile, а его целевые файлы существуютнет
Ни один шаблон files не соответствует файлуno-source-filesИсправьте шаблоны files
Исходный файл изменился с момента последнего переводаsource-changedlingo push --wait или lingo pull, если push ещё выполняется
Для исходного файла нет записи в Lockfilesource-not-pushedlingo push --wait
Целевой файл отсутствует, а исходный файл актуаленmissing-targetlingo push --backfill-missing --wait
Целевой файл отсутствует, а исходный файл изменился или ещё ни разу не отправлялся через pushmissing-targetlingo push --wait
Целевой файл изменён вручнуюнет
Lockfile отсутствует, а все целевые файлы существуютнет, с примечанием в stderr
Lockfile отсутствует, и одного из целевых файлов нетmissing-target, с примечанием в stderrlingo push --backfill-missing --wait, затем добавьте целевые файлы и .lingo/lock.json в коммит

Записи Lockfile для путей, которые больше не настроены как исходные, игнорируются. Предупреждения о целевых файлах, определённых по предположению, и пропущенных YAML-файлах, которые выводит lingo push, здесь тоже выводятся в stderr.

Как читать сообщения о проблемах #

ТипЧто проверить и исправить
missing-contextДобавьте полезный контекст к извлечённому сообщению.
stale-jsoncЗаново сгенерируйте исходный каталог и проверьте его.
stale-typesЗаново сгенерируйте объявления и включите их в проверку типов приложения.
missing-translationПроверьте активный ключ, для которого нет непустого активного значения на целевом языке.
orphanedПеред очисткой выясните, было ли сообщение удалено или пропущено при извлечении.

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

Вывод в JSON #

Вывод в JSON содержит issues и stats. Для локальной работы те же проблемы перечисляются в удобном для чтения виде.

У каждой проблемы есть type и message. У проблем React может быть src. У проблем с файлами есть file, а у проблемы missing-target — ещё и locale.

Статистика содержит messages, locales, missingContext, missingTranslations, orphaned, staleJsonc и staleTypes. Если проверки React не выполнялись, эти значения равны нулю или false. В число локалей входят обнаруженные целевые локали и исходная. Если выполнялась проверка файлов, stats.files содержит lockfile, sources, locales, changedSources и missingTargets. Эти показатели отражают согласованность данных, а не качество языка.

Как запускать в CI #

Запускайте проверку для каждого запроса на слияние, в том числе из форков:

yaml
- uses: actions/checkout@v4
- run: npx @lingo.dev/cli@latest check

Используйте те же входные параметры, что и при извлечении #

--src, --out, --types и --source-locale применяются только к проверкам React. Значение --src по умолчанию — src, а --source-locale — en. --out имеет приоритет над настроенным путём к каталогу, затем используется locales. --types имеет приоритет над настроенным путём к объявлениям, затем используется lingo.d.ts. Пути определяются относительно корня проекта. Значение исходной локали по умолчанию не зависит от конфигурации локализации. Значение --json по умолчанию — false. Этот параметр применяется к обеим проверкам.

Чтобы обновить устаревшие данные, запустите извлечение с теми же входными параметрами. Просмотрите предупреждения и изменения, затем снова запустите проверку и сборку приложения. Удаляйте только те записи, которые точно устарели, а после очистки заново сгенерируйте объявления.

Ограничения #

  • Проверка файлов работает на уровне файлов. Она не сообщает об отсутствии ключа в существующем целевом файле. Исключение — каталоги React .jsonc.
  • Локали внутри одного общего каталога, например файла .xcstrings, не проверяются. Ручная правка в таком каталоге считается изменением исходного файла.
  • Если репозиторий перешёл с CLI на GitHub App, удалите .lingo/lock.json.
  • При ошибках конфигурации, например когда два исходных файла указывают на один целевой путь или Lockfile повреждён, команда возвращает код 1, выводит сообщение в stderr и не выводит JSON.
  • Хеши исходных файлов вычисляются с точностью до байта, поэтому checkout, в котором выполнялась команда lingo push, и checkout в CI должны использовать одинаковые окончания строк. Добавьте * text=auto eol=lf в .gitattributes.

Для каталогов React целевые файлы — это файлы .jsonc в папке каталога. Если исходный каталог соответствует шаблонам files (например, locales/en.jsonc), также требуется файл для каждой настроенной целевой локали.

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

Используйте extract --check, если нужно проверить только актуальность сгенерированных данных на уровне байтов. Дополняйте эту проверку проверкой формата штатными средствами и проверкой содержимого. Успешный результат ничего не говорит о ресурсах Android, отображении Markdown или смысле перевода за пределами того, что команда действительно проверяет.