Translates a set of key-value pairs from one locale to another using a configured localization engine.
Request#
POST /process/localize| Parameter | Type | Description |
|---|---|---|
engineId | string (optional) | The localization engine ID (eng_...). Uses the default engine if omitted. |
sourceLocale | string | BCP-47 source locale (e.g., en) |
targetLocale | string | BCP-47 target locale (e.g., de) |
data | object | Key-value content to translate. Supports nested objects and arrays. |
hints | object (optional) | Contextual hints per key. Keys match data keys, values are arrays of breadcrumb strings (e.g. { "nav.home": ["Navbar", "Home link"] }). |
{
"engineId": "eng_abc123",
"sourceLocale": "en",
"targetLocale": "de",
"data": {
"greeting": "Hello, world!",
"cta": "Get started"
},
"hints": {
"cta": ["Landing page", "Primary button"]
}
}Response#
Returns the translated content along with the model that produced it and per-request usage and cost.
| Field | Type | Description |
|---|---|---|
sourceLocale | string | BCP-47 source locale, echoed from the request. |
targetLocale | string | BCP-47 target locale, echoed from the request. |
data | object | Translated key-value content, matching the input shape. |
model | string (optional) | LLM model that produced this translation, formatted provider/model (e.g. anthropic/claude-sonnet-4.5). Absent when no LLM call was made (see callout below). |
usage | object (optional) | Token counts and per-request cost in USD. Absent when no LLM call was made. |
The usage object contains:
| Field | Type | Description |
|---|---|---|
inputTokens | number | Total input tokens consumed across all chunks. |
outputTokens | number | Total output tokens generated across all chunks. |
llmCost | number | Upstream LLM provider cost in USD. 0 when no cost was reported. |
localizationCost | number | Lingo.dev's per-token cost in USD, computed from outputTokens. |
cost | number | Total request cost in USD (llmCost + localizationCost). |
{
"sourceLocale": "en",
"targetLocale": "de",
"data": {
"greeting": "Hallo, Welt!",
"cta": "Jetzt starten"
},
"model": "anthropic/claude-sonnet-4.5",
"usage": {
"inputTokens": 2789,
"outputTokens": 861,
"llmCost": 0.02129,
"localizationCost": 0.001722,
"cost": 0.023012
}
}When `model` and `usage` are absent
If data is empty (no keys to translate), the endpoint short-circuits without calling an LLM and the response omits model and usage. Every request that triggers a translation includes them.
Examples#
const response = await fetch(
"https://api.lingo.dev/process/localize",
{
method: "POST",
headers: {
"X-API-Key": "your_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify({
engineId: "eng_abc123",
sourceLocale: "en",
targetLocale: "de",
data: {
greeting: "Hello, world!",
cta: "Get started",
},
}),
}
);
const { data } = await response.json();
// { greeting: "Hallo, Welt!", cta: "Jetzt starten" }What happens during localization#
When a request hits the localize endpoint, the engine applies its full configuration:
Model selection - Selects the highest-priority LLM model matching the locale pair. Locale-specific models take precedence over wildcard (
*) models. If the primary model fails, the engine falls through to the next ranked model automatically.Brand voice - Loads the brand voice for the target locale (falls back to the wildcard brand voice if no locale-specific one exists).
Instructions - Loads all instructions matching the target locale, including wildcard instructions.
Glossary lookup - Splits input values into searchable chunks, generates embeddings, and performs a vector similarity search against the engine's glossary. Matched terms enforce exact translations or mark terms as non-translatable.
Generation - Sends the composed prompt to the selected model. Parses and validates the JSON response.
Fallback behavior
If the primary model fails, the engine automatically attempts the next model in rank order. This happens transparently - the response includes the same structure regardless of which model produced it.