Translate your first file

Create a source catalog, collect German and French target files, and translate a later source change.

This walkthrough takes one English JSON file through setup, translation, and retrieval. You finish with target files on disk and a baseline for subsequent edits. To let a coding agent do the setup, see Set up with a coding agent.

Use a small project directory with Node.js and npm available. You also need a Lingo.dev account and permission to translate through an enabled localization engine, with enough account allowance for the work.

Install and sign in #

sh
npm install --global @lingo.dev/cli
lingo --version
lingo login

Login opens the browser. For a noninteractive runner, supply LINGO_API_KEY through its secret store instead. An environment key overrides stored login, so remove an unintended key override before signing in as another person.

Create the source #

Create a locales directory and save this as locales/en.json:

json
{
  "checkout": {
    "title": "Review your order",
    "submit": "Place order"
  }
}

From the project root, run:

sh
lingo init --source en --targets de,fr --files 'locales/en.json' --yes
lingo link

init writes .lingo/config.json and adds a Lingo.dev block to AGENTS.md, so coding agents know to read the CLI's agent guides; pass --no-agents-md to skip it. link lets you select the organization and localization engine, or create them when your access permits. A localization engine supplies the models and language guidance; its ID is saved in project configuration, while your credential stays separate.

Open the config before continuing. It should name en as source, de and fr as targets, and locales/en.json as the source file. Check the organization and localization engine IDs too, especially in a copied project or fork.

Translate and retrieve #

sh
lingo push --backfill-missing --wait

Backfill requests missing target files. --wait waits and downloads completed output. A plain first push without a lockfile establishes source storage instead of requesting this initial translation.

Keep target files unchanged while the command is waiting: this direct collection path does not perform the separate pull command's fresh local-edit conflict comparison. If the run waits for review or reports failures, inspect that state before treating it as finished.

Open locales/de.json and locales/fr.json. Confirm that both checkout keys remain present and read the translated values. If you cannot assess a target language, use a qualified reviewer or applicable measurement. When integrating with an application, also load the files through its normal resource loader.

Review .lingo/lock.json alongside the source and target diff. Commit the accepted files, configuration, and baseline together. Without --wait, run lingo pull later from the same checkout and machine to collect the latest locally recorded run.

Update the source #

Change a value or add a key in locales/en.json, then run:

sh
lingo push --wait

The ordinary update compares source changes with the saved baseline. Backfill is for missing files, not new keys inside a target file that already exists.

For other resource types or layouts, use Configuration and Formats. YAML and Android XML need explicit format selection. For React source-call extraction, continue with the React quickstart; its JSONC catalog must be selected in configuration rather than assuming this JSON fixture selects it.