A clear path from strings to shipped.

Guides and reference

CLI guide: setup, sync, translation, CI and troubleshooting

Every CLI command and option

MCP guide: local and hosted setup, tool schemas, permissions and examples

Create an account first, then pair the CLI and configure the repository. init stays offline; project create creates a hosted project in the workspace you name. Choose your own workspace slug and target languages.

lingvo login --device
lingvo init
lingvo project create --workspace my-workspace --locale de --locale ja
lingvo push

Install

On macOS, Homebrew installs the Java 21 runtime with it, so this is the whole thing:

brew install merkost/lingvo/lingvo

Everywhere else, an install script that verifies its own download and writes only inside your home directory. It needs a Java 21 runtime already present — `actions/setup-java@v4` in CI, or your distribution's `openjdk-21-jre-headless` — and checks for one before it downloads anything.

curl -fsSL https://lingvo.dev/install.sh | sh

Both land the same build. Pin one with LINGVO_VERSION=0.1.0, and check what you have with lingvo --version — every published version stays at its own URL for ever, so a pinned CI job keeps resolving to the bytes it was tested against.

None of this is required to try Lingvo: importing and exporting live on each project's Data page. The CLI is for putting that same loop in CI.

Authenticate

For interactive setup, run lingvo login --device and approve your own pairing in the browser. For CI, use a project-scoped token with the permissions the job needs.

lingvo login --device

Create a token in the web app under Settings → API tokens. It is shown exactly once. Credentials resolve in a fixed order and the first hit wins.

Logging in without leaking the secret

Piping the token in means it never reaches argv, shell history or the process list. Passing it as a flag works and warns, because those three places all keep a copy.

# Best: never touches argv, history, or the process list
printf '%s' "$LINGVO_API_TOKEN" | lingvo login --token-stdin

# Also fine: read from a named environment variable
lingvo login --token-env LINGVO_API_TOKEN

# Check what would be used — no network call, never prints the token
lingvo auth status

Configure — lingvo.yaml

The config lives at the repository root. Running lingvo init writes one for you by detecting the localization files already present and inferring the project kind.

project: my-project-slug        # required — the project slug in Lingvo
source_locale: en               # required — the locale your source files are written in

files:                          # required — at least one entry
  - source: composeResources/values/strings.xml
    translation: composeResources/values-%locale%/strings.xml
    format: android_xml

  - source: iosApp/Localizable.strings
    translation: iosApp/%locale%.lproj/Localizable.strings
    format: ios_strings

generate:                       # optional — typed key accessors
  target: kotlin-object         # kotlin-object | swift-enum
  output: shared/src/commonMain/kotlin/app/Strings.kt
  package: app                  # kotlin-object only

%locale% is replaced with each target locale. Android uses its own qualifier form (values-pt-rBR), which lingvo init writes correctly for android_xml paths.

The sync loop

Three commands cover day-to-day use. None of them is metered on any plan — Lingvo does not charge for keys, languages or words.

Reading the counts

Every push and sync reports five counts. The one to watch is skipped: it means the file held keys this project does not define, so their translations went nowhere. A non-zero skipped on a translation push almost always means the wrong destination file, or a source push that never happened — not "already up to date".

Inspect and export

Machine translation

Six providers are supported. mymemory and libretranslate need no key, so machine translation works before any setup at all.

Provider ids: claude, openai, deepl, google, libretranslate, mymemory.

What credits are

One credit is one string of up to 1,000 characters, machine-translated into one language; Claude and OpenAI cost three. Longer strings cost one more credit per further 1,000 characters, and 2,000 characters is the per-string limit — past that the model drifts and the result is not reviewable. A plural is charged once, for its longest form, not once per category. A project using its own provider key spends none, because Lingvo is not paying for those calls. Running out never stops you translating by hand, importing, exporting or running QA.

Typed keys

lingvo generate reads the generate: block and emits typed accessors, so a renamed key becomes a compile error instead of a blank label in production. Name collisions are a hard error naming both keys — never a silent rename.

generate:
  - target: kotlin-object
    output: shared/src/commonMain/kotlin/app/Strings.kt
    package: app
  - target: swift-enum
    output: iosApp/Generated/L10n.swift

Keys are fetched once and written to every target. Two targets pointing at the same file is a configuration error, since whichever ran last would silently win.

In CI

Set LINGVO_TOKEN as a secret and nothing is written to disk. Branch on exit codes rather than message text — they are a stable contract.

- name: Pull translations and gate on QA
  env:
    LINGVO_TOKEN: ${{ secrets.LINGVO_TOKEN }}
  run: |
    lingvo pull
    lingvo qa --fail-on-error

Every command also takes --json, which prints a single stable envelope on stdout while human-readable progress stays on stderr.

Formats

Every format works in both directions, so you keep the native file type for each platform instead of reshaping your localization stack around the tool.

• android_xml — Android string resources, including plurals and locale qualifiers
• ios_strings, ios_stringsdict, xcstrings — Apple .strings, .stringsdict and String Catalogs
• json_nested, json_flat — the two shapes web projects actually use
• properties — Java and Spring resource bundles
• yaml — Rails and generic YAML catalogues
• csv — spreadsheets, for the people who insist
• xliff, po — the standard interchange formats, for moving work in or out

What each format carries — plurals, comments, placeholder syntax, and what does not survive a round trip — is read from the parsers themselves. Read the format matrix.

Coding agents

Read the complete MCP setup guide and tool reference

Lingvo speaks Model Context Protocol, so an agent working in your repository can read and write strings the same way you do from the CLI. One command sets it up:

lingvo agent install --client claude

That writes the client's config and a skill generated from the CLI's own command classification, so the instructions cannot describe a command that does not exist or miss one that does.

The thing worth knowing is what the agent gets to read. translation_brief hands it the same context bundle Lingvo assembles for a paid machine-translation provider — your style guide, the glossary terms that occur in the text, the CLDR plural categories the language actually uses, and for each string its developer context, its length budget, its placeholders and where it appears in your code. It is free and it spends no credits.

And an agent proposes; a person approves. There is no tool on this surface that can approve a translation, delete anything, or touch members, billing or provider keys — those do not exist here rather than being refused, which is the only defence against prompt injection that does not depend on a model behaving.

For a fleet that runs without you, create an agent connection in Settings → Agents. It carries its own scopes, a project allowlist, an autonomy level and a credit budget, all resolved on every call.

The full page: Coding agents.