Setup · Lingo.dev

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

bash

cd your-project-directory

Run the init command

bash

npx lingo.dev@latest init

Windows 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:

json

{
  "$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, rules, 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:

bash

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:

json

{
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

Step 4. Generate translations#

bash

npx lingo.dev@latest run

The 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.

Next Steps#

i18n.json

Full configuration reference

Supported Formats

JSON, YAML, Markdown, and 20+ file formats

Connect Your Engine

Route translations through your localization engine

How It Works

The five-step translation pipeline