CLI: Getting Started

This takes you from nothing installed to a report about your own project. Everything here is read-only except the one step that writes stringlane.yaml, 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:

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

  de      36/38      2 missing
  en      36/38      2 missing
  es      36/38      2 missing
  fr      39/41      2 missing
  ja      33/35      2 missing
  pl      44/44      complete
  uk      42/44      2 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. If any of that is wrong, step 3 is where you correct it.

inspect writes nothing. 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#

stringlane init .

This detects your project and shows you the stringlane.yaml it proposes before writing it. Nothing lands until you agree.

format: arb
path: lib/l10n

Commit that file. It 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 length limits live later. It will not overwrite an existing config without --force.

Step 4: Validate, not just count#

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

stringlane check .

0 errors · 3 warnings · 0 info
  warning  untranslated          de/app_name: Key "app_name" in "de" appears to be untranslated (same as base)
  warning  untranslated          fr/app_name: Key "app_name" in "fr" 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 "!"

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.

Three exit codes, and the third one matters:

• 0 — no issues
• 1 — the project has localization issues
• 2 — the command could not run

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.