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.
lingo check --jsonWhich checks run #
| Check | Runs when |
|---|---|
| Files check | .lingo/config.json has files, or the project is not React. |
| React checks | The 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.
| Case | Issue | Fix |
|---|---|---|
| A source matches its lockfile entry and its targets exist | none | |
No files pattern matches a file | no-source-files | Fix the files patterns |
| A source changed since its last translation | source-changed | lingo push --wait, or lingo pull if a push is still running |
| A source has no lockfile entry | source-not-pushed | lingo push --wait |
| A target file is missing and its source is up to date | missing-target | lingo push --backfill-missing --wait |
| A target file is missing and its source changed or was never pushed | missing-target | lingo push --wait |
| A target file was edited by hand | none | |
| No lockfile, and every target file exists | none, with a note on stderr | |
| No lockfile, and a target file is missing | missing-target, with a note on stderr | lingo 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 #
| Type | Repair to investigate |
|---|---|
missing-context | Add useful context to the extracted message. |
stale-jsonc | Regenerate and inspect the source catalog. |
stale-types | Regenerate declarations and include them in the application's typecheck. |
missing-translation | Inspect an active key without a nonempty active target value. |
orphaned | Decide 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:
- uses: actions/checkout@v4
- run: npx @lingo.dev/cli@latest checkUse 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
.jsonccatalogs. - Locales inside one shared catalog, such as an
.xcstringsfile, 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 pushand the CI checkout must use the same line endings. Add* text=auto eol=lfto.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.