Tienes una cadena, o un objeto pequeño de cadenas, que necesita estar en otro idioma ya mismo: una etiqueta de formulario, una notificación, un bloque breve de texto de UI que un usuario está esperando. No quieres montar un endpoint con webhook ni consultar un job para una sola ida y vuelta. Quieres enviar el texto y recibir la traducción de inmediato.
Para eso existe el endpoint síncrono Localize: una sola solicitud y los datos traducidos de vuelta con la misma estructura. Haces un POST de contenido clave-valor con un idioma de origen y otro de destino, la llamada queda bloqueada mientras tu motor traduce, y la respuesta te devuelve exactamente el mismo objeto, con los valores traducidos y la estructura intacta. No hay ningún job que seguir ni una segunda llamada que hacer.
La traducción no es una llamada genérica a un modelo. Pasa por el motor de localización que configuraste: su glosario, voz de marca, instrucciones y selección de modelo por idioma; el mismo motor que usa la API asíncrona. La diferencia es solo de formato: async expande una solicitud a muchos idiomas y entrega los resultados a medida que están listos; esta llamada resuelve un solo par de idiomas y lo devuelve inline.
¿Te basta con un solo idioma y una llamada bloqueante? Estás en la página correcta.
Usa este endpoint cuando necesites un solo par de idiomas y puedas esperar una ida y vuelta. Si tienes muchos idiomas de destino, contenido largo o quieres aislar fallas por idioma, la API asíncrona de localización recibe una solicitud, devuelve un 202 de inmediato y ejecuta cada idioma como un flujo de trabajo duradero e independiente en segundo plano. Hay otra diferencia además de la latencia: el pipeline de localización —preedición, revisión humana, retrotraducción y las demás etapas opcionales— solo corre en jobs asíncronos. Esta llamada síncrona ignora la configuración del pipeline.
En esta página
Solicitud#
POST /process/localizeAutentícate con el encabezado X-API-Key. Las claves tienen alcance a nivel organización y funcionan con todos los motores de tu organización. Consulta Autenticación para ver dónde generar una, y Errores y códigos de estado para conocer el modelo de errores completo.
| Parámetro | Tipo | Descripción |
|---|---|---|
engineId | string (opcional) | El ID del motor de localización (eng_...). Si lo omites, se usa el motor predeterminado de tu organización. |
sourceLocale | string | Idioma de origen en formato BCP-47 (p. ej., en). |
targetLocale | string | Idioma de destino en formato BCP-47 (p. ej., de). |
data | object | Contenido clave-valor para traducir. Se admiten objetos anidados y arreglos; la respuesta refleja exactamente la estructura que envíes. |
context | string (opcional) | Contexto general para esta carga de traducción, como la superficie del producto, la audiencia o el propósito. Se aplica a toda la solicitud. |
hints | object (opcional) | Pistas de contexto por clave. Las claves coinciden con las claves de data; los valores son arreglos de cadenas tipo breadcrumb (p. ej., { "nav.home": ["Navbar", "Home link"] }) que le indican al motor dónde vive una cadena, para desambiguar texto corto o con varios sentidos. |
{
"engineId": "eng_abc123",
"sourceLocale": "en",
"targetLocale": "de",
"data": {
"greeting": "Hello, world!",
"cta": "Get started"
},
"hints": {
"cta": ["Landing page", "Primary button"]
}
}Respuesta#
La respuesta devuelve el contenido traducido con la misma estructura que enviaste, junto con el modelo que lo generó y el costo por solicitud. Regresan las mismas claves, con el mismo anidamiento: tu código puede leer la traducción desde la estructura que ya conoce.
| Campo | Tipo | Descripción |
|---|---|---|
sourceLocale | string | Idioma de origen en formato BCP-47, devuelto tal como vino en la solicitud. |
targetLocale | string | Idioma de destino en formato BCP-47, devuelto tal como vino en la solicitud. |
data | object | Contenido clave-valor traducido, con la misma estructura de entrada. |
model | string (opcional) | El modelo LLM que produjo esta traducción, con formato provider/model (p. ej., anthropic/claude-sonnet-4.5). Revísalo para saber qué modelo de tu cadena de fallback se ejecutó realmente. No aparece cuando no se hizo ninguna llamada a un LLM; consulta el aviso de abajo. |
usage | object (opcional) | Conteo de tokens y costo por solicitud en USD. No aparece cuando no se hizo ninguna llamada a un LLM. |
El objeto usage desglosa el costo de la llamada para que puedas atribuir el gasto sin hacer una consulta aparte a facturación:
| Campo | Tipo | Descripción |
|---|---|---|
inputTokens | number | Total de tokens de entrada consumidos en todos los fragmentos. |
outputTokens | number | Total de tokens de salida generados en todos los fragmentos. |
cacheReadTokens | number | Tokens de entrada servidos desde la caché de prompts del proveedor, cuando el modelo los informa. |
cacheWriteTokens | number | Tokens de entrada escritos en la caché de prompts del proveedor, cuando el modelo los informa. |
llmCost | number | Costo del proveedor upstream de LLM en USD. 0 cuando no se reportó ningún costo. |
localizationCost | number | Costo por token de Lingo.dev en USD, calculado a partir de outputTokens. |
cost | number | Costo total de la solicitud en 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,
"cacheReadTokens": 0,
"cacheWriteTokens": 0,
"llmCost": 0.02129,
"localizationCost": 0.001722,
"cost": 0.023012
}
}Cuando `model` y `usage` no aparecen
Si data está vacío —no hay claves para traducir— el endpoint hace short-circuit sin llamar a un LLM, y la respuesta omite model y usage. Este es el único caso en el que faltan los campos de costo, y la razón es simple: no hubo costo. No se tradujo nada, así que no se gastó nada. Toda solicitud que dispara una traducción incluye ambos campos. Trátalos como opcionales en tu parser y el caso de entrada vacía no te tomará por sorpresa.
Ejemplos#
La misma llamada en cinco idiomas. Cada ejemplo envía un objeto plano por claridad; data también acepta objetos anidados y arreglos, y la respuesta vuelve con la misma estructura que envíes.
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" }Qué pasa durante la localización#
Un solo POST oculta una secuencia de pasos, y vale la pena entender cuáles son, porque explican por qué la salida es consistente con el resto de tu contenido localizado en lugar de ser una respuesta aislada del modelo. Cuando una solicitud llega al endpoint, el motor aplica toda su configuración en este orden:
Selección de modelo – Selecciona el modelo LLM de mayor prioridad que coincida con el par de idiomas. Los modelos específicos por idioma tienen prioridad sobre los modelos comodín (
*). Si el modelo principal falla, el motor pasa automáticamente al siguiente modelo en el ranking.Voz de marca – Carga la voz de marca para el idioma de destino, y recurre a la voz de marca comodín si no existe una específica para ese idioma.
Instrucciones – Carga cada instrucción que coincida con el idioma de destino, incluidas las instrucciones comodín.
Búsqueda en el glosario – Divide los valores de entrada en fragmentos que se puedan buscar, genera embeddings y ejecuta una búsqueda de similitud vectorial contra el glosario del motor. Los términos coincidentes fuerzan traducciones exactas o marcan términos como no traducibles para que pasen sin cambios.
Generación – Envía el prompt compuesto al modelo seleccionado y luego analiza y valida la respuesta JSON.
Este es el mismo pipeline de pasos del motor que la API asíncrona ejecuta por job. Llamar a sync en lugar de async cambia el formato de entrega, no la forma en que se produce la traducción. Eso significa que una cadena traducida aquí y esa misma cadena traducida en un job asíncrono terminan con los mismos términos del glosario y la misma voz.
El fallback de modelo es automático, y la respuesta te dice cuál se ejecutó
Si el modelo principal falla, el motor intenta con el siguiente modelo según el orden de prioridad. Esto ocurre de forma transparente: la estructura de la respuesta es idéntica sin importar qué modelo produjo la traducción. La única señal de que hubo fallback es el campo model en la respuesta: revísalo cuando necesites saber exactamente qué modelo de tu cadena procesó una solicitud específica.
