Tienes una cadena, o un pequeño objeto con cadenas, que necesita estar en otro idioma ya: la etiqueta de un formulario, una notificación, un breve bloque de texto de la interfaz que un usuario está esperando. No quieres montar un endpoint con webhook ni consultar un trabajo para una única ida y vuelta. Quieres enviar el texto y recibir la traducción al momento.
Para eso está el endpoint síncrono de Localize: una solicitud y los datos traducidos de vuelta con la misma estructura. Envías contenido de clave-valor con un idioma de origen y otro de destino, la llamada queda bloqueada mientras tu motor traduce, y la respuesta te devuelve el mismo objeto con los valores traducidos y la estructura intacta. No hay ningún trabajo 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 hayas configurado: su glossary, su voz de marca, sus instructions y la selección de modelos por idioma; el mismo motor que usa la API asíncrona. La única diferencia está en el formato: la API asíncrona reparte una solicitud entre muchos idiomas y entrega los resultados a medida que llegan; esta llamada trabaja con un único par de idiomas y lo devuelve en línea.
¿Te basta con un solo idioma y una llamada bloqueante? Estás en la página adecuada.
Recurre a este endpoint cuando necesites un único par de idiomas y puedas esperar una ida y vuelta. Si tienes muchos idiomas de destino, contenido largo o quieres aislar los fallos por idioma, la API de localización asíncrona acepta una solicitud, devuelve un 202 de inmediato y ejecuta cada idioma como un flujo de trabajo duradero e independiente en segundo plano. Otra diferencia, además de la latencia: el localization pipeline —preedición, revisión humana, retraducción y las demás fases opcionales— solo se ejecuta en trabajos asíncronos. Esta llamada síncrona ignora la configuración del pipeline.
En esta página
Solicitud#
POST /process/localizeAutentícate con la cabecera X-API-Key. Las claves tienen alcance de organización y dan acceso a todos los motores de tu organización; consulta Authentication para saber dónde generar una y Errors and status codes para ver el modelo de errores completo.
| Parámetro | Tipo | Descripción |
|---|---|---|
engineId | string (opcional) | El ID del motor de localización (eng_...). Si se omite, se usa el motor predeterminado de tu organización. |
sourceLocale | string | Idioma de origen BCP-47 (p. ej., en). |
targetLocale | string | Idioma de destino BCP-47 (p. ej., de). |
data | object | Contenido de clave-valor para traducir. Se admiten objetos y arrays anidados; 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 de data; los valores son arrays de cadenas de ruta jerárquica (p. ej., { "nav.home": ["Navbar", "Home link"] }) que indican al motor dónde vive una cadena, para desambiguar textos breves 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 incluye el contenido traducido con la misma estructura que enviaste, además del modelo que lo produjo y el coste por solicitud. Vuelven las mismas claves, con el mismo nivel de anidación: tu código puede leer la traducción directamente desde la estructura que ya conoce.
| Campo | Tipo | Descripción |
|---|---|---|
sourceLocale | string | Idioma de origen BCP-47, reflejado desde la solicitud. |
targetLocale | string | Idioma de destino BCP-47, reflejado desde la solicitud. |
data | object | Contenido de clave-valor traducido, con la misma estructura de entrada. |
model | string (opcional) | Modelo LLM que produjo esta traducción, con formato provider/model (p. ej., anthropic/claude-sonnet-4.5). Consúltalo para saber qué modelo de tu cadena de fallback se ejecutó realmente. No aparece cuando no se ha hecho ninguna llamada a un LLM; consulta el aviso de más abajo. |
usage | object (opcional) | Recuento de tokens y coste por solicitud en USD. No aparece cuando no se ha hecho ninguna llamada a un LLM. |
El objeto usage desglosa el coste de la llamada para que puedas atribuir el gasto sin tener que hacer una consulta de facturación aparte:
| Campo | Tipo | Descripción |
|---|---|---|
inputTokens | number | Número total de tokens de entrada consumidos en todos los fragmentos. |
outputTokens | number | Número 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 | Coste en USD del proveedor de LLM. 0 cuando no se informó de ningún coste. |
localizationCost | number | Coste por token de Lingo.dev en USD, calculado a partir de outputTokens. |
cost | number | Coste 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
}
}Cuándo faltan `model` y `usage`
Si data está vacío —no hay claves que traducir—, el endpoint se resuelve de inmediato sin llamar a un LLM, y la respuesta omite model y usage. Este es el único caso en el que faltan los campos de coste, y el motivo es simple: no hubo ningún coste. No se tradujo nada, así que no se gastó nada. Todas las solicitudes que activan una traducción incluyen ambos campos. Trátalos como opcionales en tu analizador y el caso de entrada vacía no te pillará por sorpresa.
Ejemplos#
La misma llamada en cinco idiomas. Cada una envía un objeto plano por claridad; data también acepta objetos y arrays anidados, 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é ocurre durante la localización#
Un único POST oculta una secuencia de pasos, y conviene conocerlos, porque explican por qué el resultado encaja con el resto de tu contenido localizado en lugar de parecer una respuesta puntual de un modelo. Cuando una solicitud llega al endpoint, el motor aplica su configuración completa en este orden:
Selección de modelos – 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 de la lista.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 todas las instruction que coincidan con el idioma de destino, incluidas las instrucciones comodín.
Consulta del glosario – Divide los valores de entrada en fragmentos consultables, genera embeddings y ejecuta una búsqueda de similitud vectorial en el glossary del motor. Los términos coincidentes fuerzan traducciones exactas o marcan términos como no traducibles para que pasen tal cual.
Generación – Envía el prompt compuesto al modelo seleccionado y luego analiza y valida la respuesta JSON.
Esta es la misma secuencia de pasos del motor que ejecuta la API asíncrona en cada trabajo. Llamar a la API síncrona en lugar de a la asíncrona cambia el formato de entrega, no cómo se produce la traducción; por eso, una cadena traducida aquí y esa misma cadena traducida en un trabajo asíncrono terminan usando los mismos términos del glosario y la misma voz.
El fallback de modelos es automático, y la respuesta te dice cuál se ejecutó
Si el modelo principal falla, el motor intenta usar el siguiente modelo según el orden de prioridad. Esto ocurre de forma transparente: la estructura de la respuesta es idéntica independientemente del modelo que haya producido la traducción. La única señal de que ha habido fallback es el campo model de la respuesta: consúltalo cuando necesites saber exactamente qué modelo de tu cadena gestionó una solicitud concreta.
