Connect Your Engine#

The Lingo.dev CLI connects your codebase to a localization engine through a single configuration field. Every lingo.dev run call routes through your engine — applying your brand voice, glossary, instructions, and model configuration automatically. No code changes, no new dependencies.

What changes#

	Before	After
Translation pipeline	Default Lingo.dev pipeline	Your localization engine
Brand voice	None	Applied per target locale
Glossary	None	Semantically matched per request
Instructions	None	Included per target locale
Model selection	Lingo.dev default	Your model config with fallbacks
Quality scoring	None	Your configured scorers run automatically

Setup#

Add engineId to i18n.json (optional)

To target a specific engine, add the engineId field to your i18n.json configuration. Find your engine ID in the dashboard — it starts with eng_ (e.g., eng_SxjMwMsfOIsvV1wh).

json

{
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "json": {
      "include": ["[locale]/messages.json"]
    }
  },
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

Everything else in your config stays the same — source locale, targets, buckets. If you omit engineId, the CLI uses the default engine in your organization.

Set your API key

The CLI authenticates with your Lingo.dev API key. Set it as an environment variable:

bash

export LINGO_API_KEY="your-api-key"

Or persist it in ~/.lingodotdevrc:

ini

[auth.vnext]
apiKey = your-api-key

Generate an API key from the API Keys page in the dashboard.

Run translations

bash

lingo.dev run

The CLI sends translation requests to your engine and writes the results back to your locale files — applying your brand voice, glossary, instructions, and model configuration automatically.

Configuration reference#

i18n.json#

Field	Description
`engineId`	Optional. Your engine ID (`eng_...`). If omitted, the default engine in your organization is used.

All other i18n.json fields (version, locale, buckets) work identically to the standard CLI configuration.

Environment variables#

Variable	Required	Default	Description
`LINGO_API_KEY`	Yes	—	Your Lingo.dev API key
`LINGO_API_URL`	No	`https://api.lingo.dev`	Custom API base URL (for self-hosted or staging)

What to expect#

Every translation the CLI produces flows through your engine's full pipeline:

Brand voice shapes tone and formality per locale
Glossary items enforce exact terminology via semantic matching
Instructions apply locale-specific linguistic rules
Model configs select the right LLM with automatic fallbacks
Scorers evaluate quality automatically after each request

Translations appear in Reports with trigger type api, alongside requests from the API and integrations.

Next Steps#

API Keys

Generate the API key for CLI authentication

Brand Voices

Configure how your engine translates per locale

Glossaries

Set up terminology rules before your first run

API Reference

Use the same engine programmatically

Connect Your Engine#

What changes#

	Before	After
Translation pipeline	Default Lingo.dev pipeline	Your localization engine
Brand voice	None	Applied per target locale
Glossary	None	Semantically matched per request
Instructions	None	Included per target locale
Model selection	Lingo.dev default	Your model config with fallbacks
Quality scoring	None	Your configured scorers run automatically

Setup#

Add engineId to i18n.json (optional)

To target a specific engine, add the engineId field to your i18n.json configuration. Find your engine ID in the dashboard — it starts with eng_ (e.g., eng_SxjMwMsfOIsvV1wh).

json

{
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "json": {
      "include": ["[locale]/messages.json"]
    }
  },
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

Everything else in your config stays the same — source locale, targets, buckets. If you omit engineId, the CLI uses the default engine in your organization.

Set your API key

The CLI authenticates with your Lingo.dev API key. Set it as an environment variable:

bash

export LINGO_API_KEY="your-api-key"

Or persist it in ~/.lingodotdevrc:

ini

[auth.vnext]
apiKey = your-api-key

Generate an API key from the API Keys page in the dashboard.

Run translations

bash

lingo.dev run

The CLI sends translation requests to your engine and writes the results back to your locale files — applying your brand voice, glossary, instructions, and model configuration automatically.

Configuration reference#

i18n.json#

Field	Description
`engineId`	Optional. Your engine ID (`eng_...`). If omitted, the default engine in your organization is used.

All other i18n.json fields (version, locale, buckets) work identically to the standard CLI configuration.

Environment variables#

Variable	Required	Default	Description
`LINGO_API_KEY`	Yes	—	Your Lingo.dev API key
`LINGO_API_URL`	No	`https://api.lingo.dev`	Custom API base URL (for self-hosted or staging)

What to expect#

Every translation the CLI produces flows through your engine's full pipeline:

Brand voice shapes tone and formality per locale
Glossary items enforce exact terminology via semantic matching
Instructions apply locale-specific linguistic rules
Model configs select the right LLM with automatic fallbacks
Scorers evaluate quality automatically after each request

Translations appear in Reports with trigger type api, alongside requests from the API and integrations.

Next Steps#

API Keys

Generate the API key for CLI authentication

Brand Voices

Configure how your engine translates per locale

Glossaries

Set up terminology rules before your first run

API Reference

Use the same engine programmatically