A localization engine is a stateful translation API you build and configure on Lingo.dev. Instead of sending strings to a generic LLM and hoping the output matches your expectations, you build an API that produces the translations you actually expect - consistently, across every locale, on every request.
What a localization engine does#
Each engine combines five configurable layers. When a translation request arrives, the engine applies all of them automatically - no prompt engineering per request, no manual intervention.
| Layer | What it controls | Docs |
|---|---|---|
| LLM Models | Which model handles each locale pair, with ranked fallback chains | LLM Models → |
| Brand Voice | How your product speaks in each language - tone, formality, style | Brand Voices → |
| Rules | Discrete linguistic conventions per locale, grouped into rulesets | Rules → |
| Glossary | Exact term mappings per locale, with semantic matching - highest precedence in the engine | Glossaries → |
| AI Reviewers | Automated evaluation using an independent LLM, after each translation | AI Reviewers → |
Configuration is organization-owned#
Glossaries, rulesets, and brand voices belong to your organization, not to one engine. An engine applies them by attachment, so the same glossary can govern five engines and one edit reaches all of them. Model configs stay engine-owned.
| Container | Holds | |
|---|---|---|
| Glossary | Glossary | Terms |
| Rules | Ruleset | Rules |
| Brand Voice | Brand voice | One text per target locale |
Deleting an engine leaves all three intact. Deleting one of them is refused while an engine still applies it - detach first.
How the layers interact#
The engine applies layers in a defined order, with a clear precedence hierarchy:
- Glossary - highest precedence. If a glossary term matches, it overrides model judgment.
- Rules - medium precedence. Locale-specific linguistic conventions guide the model.
- Brand voice - sets overall context. Tone, formality, and style for the locale.
The model config determines which LLM processes the request, with automatic fallback if the primary model fails. AI reviewers run asynchronously after the translation completes - they never block the response.
Complementary, not competing
Design glossary, rules, and brand voice to complement each other. The glossary handles exact terms, rules handle locale-specific conventions, and the brand voice sets the overall voice. If a glossary term conflicts with a rule, the glossary wins.
Jobs submitted via the Async Localization API can also run through an optional pipeline - AI pre-edit of the source, human review, AI post-edit, and a back-translation drift check.
Defaults#
When you create a new engine, it comes pre-configured with model defaults - primary models and fallbacks selected from three years of weekly localization research, optimized for quality across common and low-resource languages alike. Most teams won't need to change them.
These defaults are designed to work well out of the box. You can edit any model config, swap providers, add fallbacks, or override specific locale pairs - but the defaults already reflect what we've found works best across hundreds of language pairs. A new engine applies no glossary, ruleset, or brand voice - attach the ones your organization already has, or create them as you learn what your product needs in each locale.
Using engines#
Engines are accessible through every Lingo.dev integration:
| Integration | How it connects |
|---|---|
| CLI | Set engineId in .lingo/config.json - every lingo push routes through your engine |
| API | Call the localize endpoint with your API key - the engine applies all layers automatically |
| CI/CD | Same CLI config - translations run through your engine on every pull request |
| MCP | AI coding assistants can configure and use engines directly from the conversation |
If you omit engineId, the default engine in your organization is used.
Observability#
Every translation request is logged: model used, tokens consumed, whether a fallback handled it, which glossary terms and rules were applied. Monitor engine performance in Reports and translation quality in AI Reviewers.
Test engine configurations before they go live in the Playground - compare your engine against a raw model, or compare two engines side by side.
