Lingo check
Завершайте CI с ошибкой, если переводы устарели, и проверяйте каталоги React.
lingo check завершается с ошибкой, если переводы устарели. Команда сравнивает каждый исходный файл с .lingo/lock.json, проверяет наличие всех целевых файлов, а в проектах @lingo.dev/react — ещё и извлечённые каталоги, объявления, контекст и переводы.
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-changed | lingo push --wait или lingo pull, если push ещё выполняется |
| Для исходного файла нет записи в Lockfile | source-not-pushed | lingo push --wait |
| Целевой файл отсутствует, а исходный файл актуален | missing-target | lingo push --backfill-missing --wait |
| Целевой файл отсутствует, а исходный файл изменился или ещё ни разу не отправлялся через push | missing-target | lingo push --wait |
| Целевой файл изменён вручную | нет | |
| Lockfile отсутствует, а все целевые файлы существуют | нет, с примечанием в stderr | |
| Lockfile отсутствует, и одного из целевых файлов нет | missing-target, с примечанием в stderr | lingo 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 #
Запускайте проверку для каждого запроса на слияние, в том числе из форков:
- 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 или смысле перевода за пределами того, что команда действительно проверяет.