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 #
npm install --global @lingo.dev/cli
lingo --version
lingo loginLogin 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:
{
"checkout": {
"title": "Review your order",
"submit": "Place order"
}
}From the project root, run:
lingo init --source en --targets de,fr --files 'locales/en.json' --yes
lingo linkinit 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 #
lingo push --backfill-missing --waitBackfill 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:
lingo push --waitThe 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.