Do I need to run stringlane init first?

Not always. inspect and check will detect a standard project layout on their own. Running init writes what it detected to stringlane.yaml so the app, the CLI and your teammates all agree, which matters as soon as more than one thing reads the project. In a new project it also turns on source stamps and writes .stringlane/source-stamps.json, so check can report translations that went stale when the English changed. Commit both files.

Why does stringlane check exit 1 on a project I think is fine?

Exit 1 means the project has localization issues, which is the command doing its job. Run it without --json to read the findings. If they are all pre-existing debt you are not fixing today, record a baseline so only new issues fail the gate.

CLI: Getting Started

Install the stringlane CLI, point it at a project, and get your first report. About five minutes, and nothing is written to your repository unless you say so.

This takes you from nothing installed to a report about your own project. Nothing here writes into your project except step 3, which writes stringlane.yaml and .stringlane/source-stamps.json, and that step asks first.

Step 1: Install#

You need Node 22 or newer.

npm install -g @stringlane/cli

Check it landed:

stringlane --version

Other install routes, and how to update or remove it, are in Install and update.

Step 2: Point it at a project#

Change into a repository that has localization files and run:

stringlane inspect .

You get the shape of the project and how complete each locale is. This is a small Flutter project with three locales:

arb · single-origin · base en (detected)
3 locales · 9 keys · 61% of strings filled
 
  de      5/9        4 missing
  en      9/9        complete
  uk      5/9        4 missing

The first line is what it detected: the format, whether the locales live in one file or many, and which locale is the base. (detected) after the base means StringLane guessed it from your file names. If any of that is wrong, step 3 is where you correct it.

The second line counts strings, where each plural form is one string. The rows under it count keys, all out of the same total: a key is done when every form its language needs is filled. So a project with plurals can read 61% of strings filled above rows of 5 keys out of 9.

inspect writes nothing into your project. If it cannot find localization files at all, it says so rather than reporting an empty project as a healthy one.

Step 3: Record the layout, and start tracking stale translations#

stringlane init .

This detects your project and shows you what it proposes to write before writing it. Nothing lands until you agree. In a new project that loads cleanly it proposes two files: stringlane.yaml, with source stamps turned on,

format: arb
path: lib/l10n
sourceStamps: true

and .stringlane/source-stamps.json, which records the English text each translation was confirmed against. After you agree it says what it did:

Wrote .stringlane/source-stamps.json.
Wrote stringlane.yaml.
Stamped 10 translations in 2 locales as current against today's base text. StringLane cannot know whether they were current before today.
Commit both files.

Commit both. stringlane.yaml is what makes the desktop app, the CLI and every teammate read the project the same way, and it is where per-project settings like guarded terminology and the base locale live later. The stamps file is what lets check tell you, from now on, which translations went stale when the English changed. A check with sourceStamps: true and no stamps file exits 2, so a stamps file left out of the commit breaks CI.

init stamps every existing translation as current against today's English, because it cannot know whether they were current before today. Review them when you can. Stale and unconfirmed translations explains what check reports from here.

init will not overwrite an existing config without --force, and --force writes no stamps file.

Step 4: Validate, not only count#

inspect counts what is missing. check also runs every validation rule and sets an exit code:

stringlane check .

arb · single-origin · base en (detected)
3 locales · 9 keys · 61% of strings filled
 
  de      5/9        4 missing
  en      9/9        complete
  uk      5/9        4 missing
 
8 errors · 2 warnings · 0 info
  warning  untranslated  de/appTitle: Key "appTitle" in "de" appears to be untranslated (same as base)
  error    missing_key   de/errorNetwork: Key "errorNetwork" exists in base locale but is missing in "de"
  error    missing_key   de/menuItemHelp: Key "menuItemHelp" exists in base locale but is missing in "de"
  error    missing_key   de/pendingCount: Key "pendingCount" has no plural translations in "de"
  error    missing_key   de/quickActionOpen: Key "quickActionOpen" exists in base locale but is missing in "de"
  warning  untranslated  uk/appTitle: Key "appTitle" in "uk" appears to be untranslated (same as base)
  error    missing_key   uk/errorNetwork: Key "errorNetwork" exists in base locale but is missing in "uk"
  error    missing_key   uk/menuItemAbout: Key "menuItemAbout" exists in base locale but is missing in "uk"
  error    missing_key   uk/pendingCount: Key "pendingCount" has no plural translations in "uk"
  error    missing_key   uk/quickActionOpen: Key "quickActionOpen" exists in base locale but is missing in "uk"
 
1 warning(s):
  No source files were read, so nothing can be said about which keys are used. Check that the project folder contains the source code that calls these keys.

That is the same project as step 2. Each finding names the code, the locale and the key, so it is greppable and so you can decide per code what should fail a build. The last warning comes from the unused-key scan: this example has locale files and no source code, so the scan says it read nothing rather than calling every key unused. In your own repository it reads your code. See Unused keys.

Four exit codes, and the difference between 1 and 2 matters:

0: no issues
1: the project has localization issues
2: the command could not run
3: something StringLane depends on, such as the npm registry, did not answer

A broken gate and a failing gate are different answers, and a pipeline should not confuse them.

Step 5: Decide what happens next#

You now have a working report. Where you take it depends on what you were trying to fix:

You want CI to catch this. Go to Run it in CI. If the project already has debt, record a baseline first so the gate starts green.
You want your coding agent to fill the gaps. Go to The agent workflow. No API key is involved: your agent's own model does the translating.
You want the CLI to translate them itself. Go to Translate with your own key. That is the one command that costs money, and it asks before it spends any.