lingo check

Fail CI when translations are out of date, and check React catalogs.

lingo check fails when translations are out of date. It compares each source file with .lingo/lock.json, requires every target file, and in @lingo.dev/react projects also checks extracted catalogs, declarations, context, and translations.

sh
lingo check --json

Which checks run #

CheckRuns when
Files check.lingo/config.json has files, or the project is not React.
React checksThe root package.json, or the one nearest to --src, lists @lingo.dev/react, @lingo.dev/react-next, or @lingo.dev/react-tanstack, or the generated declarations file (lingo.d.ts by default) exists.

A React project with files gets both. If no files pattern matches a file, the check fails with no-source-files, as lingo push does, except in a React project, where only the React checks run and stderr says so. A project with neither files nor React fails with the same configuration error as lingo push.

lingo check needs no API key and writes nothing. Apart from CLI telemetry, which DO_NOT_TRACK=1 turns off, it makes no network call. It exits 1 when it reports any issue or hits a configuration error (for example a target collision or a corrupt lockfile), and 0 otherwise.

Files check #

Sources are the files lingo push would send. Targets are the paths push would write for every configured target locale.

CaseIssueFix
A source matches its lockfile entry and its targets existnone
No files pattern matches a fileno-source-filesFix the files patterns
A source changed since its last translationsource-changedlingo push --wait, or lingo pull if a push is still running
A source has no lockfile entrysource-not-pushedlingo push --wait
A target file is missing and its source is up to datemissing-targetlingo push --backfill-missing --wait
A target file is missing and its source changed or was never pushedmissing-targetlingo push --wait
A target file was edited by handnone
No lockfile, and every target file existsnone, with a note on stderr
No lockfile, and a target file is missingmissing-target, with a note on stderrlingo push --backfill-missing --wait, then commit the target files and .lingo/lock.json

Lockfile entries for paths that are no longer configured sources are ignored. The guessed-target and skipped-YAML warnings that lingo push prints also appear here, on stderr.

Read an issue #

TypeRepair to investigate
missing-contextAdd useful context to the extracted message.
stale-jsoncRegenerate and inspect the source catalog.
stale-typesRegenerate declarations and include them in the application's typecheck.
missing-translationInspect an active key without a nonempty active target value.
orphanedDecide whether the message was removed or extraction missed it before cleaning.

Files-check issues and their fixes: see Files check.

JSON output #

JSON output contains issues and stats. Human-readable output lists the same problems for local use.

Each issue has type and message. React issues can have src; files issues have file, and a missing-target issue also has locale.

Stats contain messages, locales, missingContext, missingTranslations, orphaned, staleJsonc, and staleTypes, which read zero or false when the React checks did not run. Locale count includes discovered targets plus source. When the files check ran, stats.files contains lockfile, sources, locales, changedSources, and missingTargets. These describe consistency, not measured language quality.

Run it in CI #

Run it on every pull or merge request, including from forks:

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

Use the same inputs as extraction #

--src, --out, --types, and --source-locale apply to the React checks only. --src defaults to src, and --source-locale to en. --out overrides configured catalog path, then locales; --types overrides configured declaration path, then lingo.d.ts. Paths resolve from the project root. The source-locale default is independent of localization configuration. --json defaults to false and applies to both checks.

Run extraction with those same inputs to repair staleness. Inspect warnings and the diff, then rerun check and the application build. Clean only confirmed obsolete entries, and regenerate declarations afterward.

Limits #

  • The files check works on files. A key missing inside an existing target is not reported, except inside React .jsonc catalogs.
  • Locales inside one shared catalog, such as an .xcstrings file, are not checked, and a hand edit inside one counts as a changed source.
  • A repository that moved from the CLI to the GitHub App should delete .lingo/lock.json.
  • Configuration errors, such as two sources that resolve to the same target or a corrupt lockfile, exit 1 with a message on stderr and no JSON.
  • Source hashes are byte-exact, so the checkout that ran lingo push and the CI checkout must use the same line endings. Add * text=auto eol=lf to .gitattributes.

For React catalogs, targets are the .jsonc files in the catalog directory. When the files patterns match the source catalog (for example locales/en.jsonc), every configured target locale file is required too.

Only missing-context extraction warnings become context issues. Dynamic-expression warnings and collision information are not an exhaustive failure gate here; extraction itself enforces collision failure. A nonempty source-language placeholder can also pass presence checking without being a translation.

Use extract --check when only generated-byte freshness is required. Keep native format validation and content review alongside this checker; a pass says nothing about Android resources, Markdown rendering, or translation meaning outside its actual checks.