PlatformCreate an account

Quickstart

Max PrilutskiyCEO & Co-Founder2 min read

End-to-end: install, authenticate, link to an engine, push sources, pull translations.

Prerequisites

Node.js 22+ (node -v to check). The CLI runs as lingo once installed.

Setup#

1

Install

bash
npm install -g @lingo.dev/cli

Or pnpm add -g @lingo.dev/cli / yarn global add @lingo.dev/cli / bun add -g @lingo.dev/cli.

2

Authenticate

bash
lingo login

Enter your email; the CLI sends a one-time code and stores a session token in ~/.lingo/auth.json. For CI / non-interactive contexts use an API key: lingo login --api-key lk_... (or set --api-key as a global flag on any command).

3

Initialize the project

In your project root:

bash
lingo init

Prompts for source locale, target locales, and file patterns (globs that point at your source files). Writes the localization section into .lingo/config.json. Commit this file — it's the source of truth for what gets translated.

4

Link to an engine

bash
lingo link

Pick (or create) an organization and a localization engine. The engine holds your AI model config, glossaries, brand voice, and rules — set it up once on the Lingo.dev platform and reuse it across projects. link appends orgId and engineId to .lingo/config.json (also committed).

First push#

With a non-empty source file in place (e.g. locales/en.json):

bash
lingo push --backfill-missing --wait

Translates every missing target across every configured pattern. --wait keeps the CLI attached until the run completes, then writes outputs (locales/de.json, locales/fr.json, ...) to disk. On a clean checkout this takes anywhere from seconds (small JSON) to minutes (large markdown bundles). Without --wait, push exits as soon as the run is submitted and lingo pull writes the outputs later.

When it finishes:

text
✓ Run lrg_a8c... : localized 12 target file(s), uploaded 1 new artifact(s).

Subsequent runs#

After you edit source files, plain lingo push only translates the delta — files whose source hash didn't change are skipped server-side. Local target edits are preserved by default; pass --force (with a scope) to overwrite.

bash
lingo push                       # delta only
lingo push docs/en/**/*.md       # scoped: only this subtree
lingo push docs/en/about.md -f   # scoped + force: retranslate even if up to date

Each of these exits once the run is submitted — add --wait to write the outputs in the same command, or collect them with lingo pull.

Pulling later#

push records the run ID in ~/.lingo/runs/<hash>.json (keyed by absolute project path). Later, on the same machine and from the same checkout:

bash
lingo pull

…waits for the last push to finish if it's still running, then writes its outputs. Useful after closing the terminal mid-translation. Other machines get the translations once you commit them.

Where to next#

  • Configuration — .lingo/config.json schema, lockfile, where run state lives.
  • lingo push — scoped patterns, --force, retry semantics.
  • lingo pull — conflict detection, --dry-run.