Inspect and Check a Project

Two commands, both read-only with respect to your repository: neither writes a lock file, a re-saved locale file, or anything else inside your project.

check does keep one thing between runs — a cache of which source files it has already scanned for key usage — and it lives in StringLane's own state directory, keyed by a hash of the project path. Never in your repository, so there is nothing to add to .gitignore. STRINGLANE_STATE_HOME moves it; see the CI guide for the runners that need that.

Look at a project#

stringlane inspect .

arb · single-origin · base en
7 locales · 35 keys · 96% complete

  de      36/38      2 missing
  pl      44/44      complete
  uk      42/44      2 missing

The header names what was detected: the format, whether every locale lives in one file (single-origin) or several, and which locale is the base. Counts are cells rather than keys, so a plural key contributes one cell per quantity the target language requires — which is why a locale can show more total cells than another.

Validate it#

stringlane check .

Everything inspect prints, plus the findings, plus an exit code:

1 error · 3 warnings · 0 info
  warning  untranslated          de/app_name: Key "app_name" in "de" appears to be untranslated (same as base)
  warning  punctuation_mismatch  fr/greeting: Key "greeting" in "fr" needs a non-breaking space before "!" — found a plain space before "!"
  error    missing_key           fr/item_count[many]: Plural quantity "many" for "item_count" is missing in "fr"

Each line is severity, code, locale/key, then the message. The codes are stable and greppable: the full list is in the validation code reference.

Exit 0 clean, 1 issues, 2 could not run. See exit codes and the JSON protocol.

Adopt it on a project that is not clean#

Most real projects fail on day one. A repository translated by several people over a couple of years carries hundreds of missing keys, and a gate that goes red on its first run is a gate somebody switches off that afternoon.

So record where you are:

stringlane baseline write . --yes
git add .stringlane/baseline.yaml

check now passes, and from that point it fails only on issues that are new.

Three things about how that behaves, because they are the difference between a baseline and just muting the problem:

Recorded issues are reported, not hidden. Every run prints how many are accepted. The debt is visible in the output and in your repository, in a file your team can read.

Fixing something is noticed. When a recorded issue no longer exists, its entry goes stale: still reported, still suppressing, and cleared the next time you run baseline write. It does not silently vanish, and you are not surprised by a gate that starts failing because a file was tidied.

Nothing expires on a timer. A baseline entry suppresses until somebody rewrites the file. A gate that turns red on a date nobody chose is a gate that gets disabled, and then the project has no gate at all.

Narrow what fails the build#

While you dig out, you can let only some kinds of issue set exit 1:

stringlane check . --fail-on missing_key,icu_parse_error

--fail-on can only ever soften the result, never harden it. A run that could not read your project still exits 2 whatever you pass, because "the gate failed" and "the gate could not run" are different answers.

It composes with a baseline rather than replacing it: the baseline decides which findings are eligible to fail at all, and --fail-on filters what is left. An accepted finding stays accepted either way.

Get it as data#

stringlane check . --json --output stringlane-report.json

The envelope carries the same figures the human report shows, plus every finding with its code, severity, locale, key and message. Its shape is in the protocol reference.

--output refuses to write over a file the project loaded as a translation file. A report should never replace your translations.