Install the Lingo.dev CLI, configure your project, and generate your first translations.
Prerequisites
Node.js 18 or higher is required. Run node -v to check your version.
Step 1. Initialize a project#
Navigate to your project
cd your-project-directoryRun the init command
npx lingo.dev@latest initWindows users: If npx lingo.dev doesn't work, install the package first with npm install lingo.dev@latest, then use npx lingo instead.
Follow the prompts. The CLI creates an i18n.json configuration file in your project root.
Step 2. Configure a bucket#
In i18n.json, configure at least one bucket - a file format paired with include patterns that tell the CLI where translatable content lives:
{
"$schema": "https://lingo.dev/schema/i18n.json",
"version": "1.15",
"locale": {
"source": "en",
"targets": ["es", "fr", "de"]
},
"buckets": {
"json": {
"include": ["locales/[locale].json"]
}
}
}The [locale] placeholder resolves to your configured locale codes at runtime - locales/en.json for source, locales/es.json for Spanish, and so on.
For the full list of supported file formats and their bucket configurations, see Supported Formats.
Step 3. Connect a translation backend#
The CLI needs a translation backend to generate translations. Two options:
A localization engine on Lingo.dev applies brand voice, glossary, instructions, and model configuration to every translation request automatically.
Create an account and generate an API key from the API Keys page.
Set the API key as an environment variable:
export LINGO_API_KEY="your-api-key"No additional configuration is needed - the CLI uses your organization's default localization engine. To target a specific engine, add engineId to your i18n.json:
{
"engineId": "eng_SxjMwMsfOIsvV1wh"
}Step 4. Generate translations#
npx lingo.dev@latest runThe CLI discovers your source files, extracts translatable content, sends it to your configured translation backend, and writes the results back to disk. An i18n.lock file is created to track what has been translated - commit it alongside your locale files.