Translate a file with CLI v0
Reproduce a small legacy catalog run with a pinned package and inspect its output and lockfile.
Use this procedure for an installed i18n.json project or an isolated legacy fixture. It targets lingo.dev@0.138.10, whose manifest requires Node.js 18 or later. Check node --version and your installed lingo --version first. New projects should use the current quickstart.
Use the recorded package #
Keep an existing project's pinned dependency. For a separate fixture, choose the package manager you use:
npm install --save-dev lingo.dev@0.138.10
pnpm add --save-dev lingo.dev@0.138.10
yarn add --dev lingo.dev@0.138.10
bun add --dev lingo.dev@0.138.10Run only one install command. Invoke the local binary through npm exec -- lingo, pnpm exec lingo, yarn lingo, or bun run lingo. The examples below abbreviate that as lingo. On Windows, a local pinned installation and package-manager binary invocation also avoids relying on package-name command resolution.
Create the catalog and configuration #
Run lingo init from the directory that should own the project. It creates i18n.json; preserve an existing file instead of reinitializing it. Create locales/en.json:
{
"welcome": "Welcome back",
"button.save": "Save changes"
}Use the matching JSON bucket:
{
"$schema": "https://lingo.dev/schema/i18n.json",
"version": "1.15",
"locale": { "source": "en", "targets": ["es"] },
"buckets": {
"json": { "include": ["locales/[locale].json"] }
}
}version is the config schema version, not the package version. This pattern reads English from locales/en.json and writes Spanish to locales/es.json.
Supply the translation backend #
For Lingo.dev, supply LINGO_API_KEY through your shell's secret mechanism. Add the intended engineId to configuration and ensure the key can translate through that localization engine. If omitted, the backend's implicit selection applies; current service policy can require an explicit ID.
Direct-provider v0 configuration is a separate choice with provider-specific credentials or a reachable Ollama service. Its configuration reference explains the fields. They do not belong in the current CLI's JSON config.
Run and inspect #
lingo runInspect locales/es.json for both keys and the actual translated values. Confirm that the save message still names the intended action. When connecting to an application, load the target through its real catalog loader. Commit the accepted output, config, and i18n.lock together.
An ordinary unchanged-source run should retain present target values. Source changes or force can replace them. Target-locale and key-scoped runs do not refresh an existing source baseline, and frozen mode can initialize a missing lockfile. Read baseline settlement before treating narrow output as a fully updated project.
For development, lingo run --watch observes source changes until stopped with Ctrl+C. Before expanding the fixture, inspect existing translation adoption and manual target ownership.