Five minutes from an empty project to translated files.

Install

The CLI is a single executable JAR that needs a Java 21 runtime. Build it from the repository, then put the wrapper somewhere on your PATH.

./gradlew :cli:installDist
export PATH="$PATH:$PWD/cli/build/install/lingvo/bin"

lingvo --version

Authenticate

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 machine-translated into one language; Claude and OpenAI cost three. 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 interchange formats every other tool speaks