Skip to main content

Validate

lingo-tracker validate is the release gate. It reads every collection and every target locale, collects every problem, prints a report and exits with code 1 when anything would ship broken or unreviewed. It never prompts and never writes.

lingo-tracker validate [--allow-translated] [--skip-locales <a,b>] [--skip-icu] [--skip-placeholders] [--skip-protected-terms] [--require-portable-plurals]

What it checks​

Each resource and target locale is asked four independent questions. Any "no" is a failure.

QuestionCheckDisable with
Has a person approved this translation?Status must be verified. translated is a failure unless --allow-translated turns it into a warning. new, stale and a missing metadata record always fail.
Does the value compile?Every stored value, including the source, is compiled as an ICU message under the locale it is stored under.--skip-icu
Are the arguments intact?The translation must use the same ICU argument names as the source. {name} becoming {Name} is a failure, because ICU renders a missing argument as empty text.--skip-placeholders
Are protected terms intact?The translation must contain every protected term found in the source, spelled exactly as stored. A missing or broken terms file only warns and supplies no terms.--skip-protected-terms

Two further checks only warn:

  • Preferred terminology. Source values are scanned for discouraged terms from the preferred-terminology file. One warning per key and rule. There is no flag to turn this off; remove the rules instead. A rule file that exists but cannot be loaded is a failure, so a typo in the file cannot silently switch the check off in CI.
  • Portable plurals, with --require-portable-plurals. Warns when a source plural selects a branch by category (one, few) rather than an exact =N match. See below.

Folders whose resource_entries.json or tracker_meta.json is not valid JSON are listed as unreadable and fail the run.

Why the ICU check matters even for verified strings​

Status says a human approved the wording. It says nothing about whether the message parses. Plural categories belong to the language:

LocaleCounts that select one
en de es nl sv1
fr pt0 and 1
is1, 21, 31, 41, …
ja ko zhnone; the category does not exist

ICU rejects the whole message, not just the offending branch:

ja  {count, plural, one {1 warning} other {# warnings}}     fails to compile, renders nothing
ja {count, plural, other {# warnings}} renders

A source string copied into a ja slot as a new placeholder carries the one branch with it, and a translator who treats a selector as prose (ein, andere) or drops the = from =1 produces the same failure. Compiling under one locale for the whole project would miss all of it, which is why each value is compiled under its own locale.

Transloco's {{ }} interpolation is normalized to ICU before compiling, so =1 {{{name}}} is not reported.

A locale code that is not well-formed BCP 47, typically fr_CA for fr-CA, cannot be compiled against. It is reported once as a configuration problem rather than per value.

Portable plurals​

--require-portable-plurals flags source values that select by category:

=1 {1 warning} other {# warnings}     portable
one {1 warning} other {# warnings} breaks when copied to ja or ko

Because the source value is what gets copied into every new locale slot, fixing it at the source stops the failure from recurring on every import. The check applies to the base locale only, is a warning, and parses rather than compiles, so it still runs with --skip-icu. selectordinal is exempt: English ordinal one legitimately selects 1, 21, 31, and so on.

Options​

FlagEffect
--allow-translatedtranslated is a warning. Use for staging.
--skip-locales <a,b>Exclude target locales still in progress. Unknown codes warn and are ignored; the base locale is ignored silently. Skipping every target locale exits 1 rather than passing vacuously.
--skip-icuDo not compile values. The braced-placeholder check still runs.
--skip-placeholdersDo not compare argument names.
--skip-protected-termsDo not check protected terms.
--require-portable-pluralsAdd the portable-plural warning.

Exit codes​

CodeMeaning
0Every check passed, possibly with warnings
1Any failure above, or a configuration problem: no config file, no collections, no target locales, all target locales skipped, or an unreadable preferred-terminology file

Output​

❌ Validation FAILED

📊 Validation Statistics:
──────────────────────────────────────────────────
Total Resources Validated: 102
Unique Resource Keys: 51
Locales Validated: 2
Collections Validated: 1

📈 Status Breakdown:
──────────────────────────────────────────────────
✅ Verified: 93
✏️ Translated: 3
⚠️ Stale: 2
❌ New: 4

❌ Failures (9):
──────────────────────────────────────────────────
Locale: es (6 failures)
❌ [main] apps.common.buttons.submit (new)
⚠️ [main] apps.common.buttons.save (stale)
✏️ [main] apps.common.buttons.cancel (translated)
...

⚠️ Preferred terminology warnings (1):
──────────────────────────────────────────────────
[main] budget.summary: consider "Investment" instead of "Expenditure"

──────────────────────────────────────────────────
📋 Summary:
Total Failures: 9
Total Warnings: 1
Total Successes: 93

❌ Validation failed. Please review the failures above.

The report goes to stdout; warnings also go to stderr. Verified resources are not listed individually. Within each locale at most 100 failures and 100 warnings are printed, followed by ... and N more; preferred-terminology warnings are capped at 100 in total. There is no JSON output and no summary file; capture stdout if you need a record.

Using it​

Strict gate for production and pull requests:

lingo-tracker validate

Staging gate that accepts machine or vendor translations that nobody has reviewed yet:

lingo-tracker validate --allow-translated

A locale that was just added and is still being translated:

lingo-tracker validate --skip-locales de

Typical pipeline order is validate, then bundle, then build, so a failed gate costs no build time. Complete examples are in the CI/CD guide.

Limits​

  • Always checks all collections. There is no collection or tag filter. Partial validation would defeat the purpose of a release gate.
  • Checks syntax and bookkeeping, not translation quality. A verified translation with the wrong meaning passes.
  • Reads statuses from metadata; it does not recompute checksums. Run normalize first if files were edited by hand or merged.

After a failed run​

FailureNext step
Many new or stalelingo-tracker export --format xliff sends exactly those to a translator; import the result, then validate again.
translatedA reviewer sets Verified in the editor, or imports the approved file with --strategy verification.
ICU compile errorFix the plural or select for that locale in the editor. For a copied source string, translate it properly or remove the categories the locale lacks.
Argument mismatchRestore the original placeholder name. Import repairs these automatically when it can; validate reports what remains.
Protected term alteredRestore the term as spelled in the terms file.
Unreadable folderFix the JSON by hand, usually a merge-conflict leftover, then run normalize.