Localization API#

The Lingo.dev localization API provides two endpoints: one for translating key-value data through a configured localization engine, and one for detecting the language of arbitrary text.

Authentication#

All API requests require an API key passed in the X-API-Key header.

X-API-Key: your_api_key

API keys are scoped to an organization. Each key has access to all localization engines within that organization. Generate keys in the API Keys section of the dashboard.

Localize#

Translates a set of key-value pairs from one locale to another using a configured localization engine.

Request#

POST /process/localize

{
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "greeting": "Hello, world!",
    "cta": "Get started"
  }
}

Response#

Returns the same structure with translated values.

{
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "greeting": "Hallo, Welt!",
    "cta": "Jetzt starten"
  }
}

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:

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

2. Brand voice — Loads the brand voice for the target locale (falls back to the wildcard brand voice if no locale-specific one exists).

3. Instructions — Loads all instructions matching the target locale, including wildcard instructions.

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

5. Generation — Sends the composed prompt to the selected model. Parses and validates the JSON response.

Recognize#

Detects the language of a given text and returns structured locale metadata.

Request#

POST /process/recognize

{
  "text": "Bonjour le monde",
  "labelLocale": "en"
}

Response#

{
  "locale": "fr",
  "language": "fr",
  "region": null,
  "script": null,
  "label": "French",
  "direction": "ltr"
}

Examples#

const response = await fetch(
  "https://api.lingo.dev/process/recognize",
  {
    method: "POST",
    headers: {
      "X-API-Key": "your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Bonjour le monde",
      labelLocale: "en",
    }),
  }
);

const result = await response.json();
// { locale: "fr", language: "fr", label: "French", direction: "ltr", ... }

When regional markers are present in the text (e.g., Brazilian Portuguese vocabulary), the response includes the full tag (pt-BR). When the regional variant is indistinguishable, only the language subtag is returned (pt).

Next Steps#