Tienes contenido en un idioma y usuarios que leen en muchos. La API existe para cerrar esa brecha de forma programática: envías texto, lo recibes traducido y cada traducción pasa por un motor de localización que configuras una sola vez. El motor aplica tu glosario, tu voz de marca, tus instrucciones y tu selección de modelo por idioma en cada llamada, para que el resultado suene como tu equipo ha decidido, y no como lo haya interpretado un modelo genérico.
Y eso deja una sola decisión: cuánto necesitas traducir de una vez. Traduce un solo idioma en una solicitud y lee el resultado directamente en la respuesta, o entrégale a la plataforma varios idiomas y deja que traduzca cada uno como un trabajo independiente en segundo plano mientras tu aplicación sigue respondiendo. Esta página explica la URL base, esa decisión y por dónde seguir.
Lo que da por hecho esta API
Esta es la referencia para traducir de forma programática. Da por hecho que has decidido localizar desde tu propio código o pipeline, no desde el panel, y que ya tienes una clave de API. ¿Acabas de llegar a la plataforma? El concepto de motor de localización es lo primero que conviene entender; todo aquí pasa por él.
En esta página
- URL base
- Dos formas de traducir
- Asíncrono: varios idiomas como trabajos
- Síncrono: una solicitud, una respuesta
- Siguientes pasos
URL base#
Todos los endpoints REST de esta referencia cuelgan del mismo host:
https://api.lingo.devCada solicitud también lleva una cabecera, X-API-Key. La clave está vinculada a la organización y solo se muestra una vez al crearla; las reglas completas para enviarla están en Authentication, y lo que devuelve la API cuando se rechaza una solicitud está en Errors and status codes.
Dos formas de traducir#
Detrás de ambos modos están el mismo motor, el mismo glosario y la misma voz de marca. Lo único que cambia es quién asume la espera.
Una llamada síncrona traduce un par de idiomas y devuelve los datos traducidos en la respuesta. Es la opción más sencilla —una solicitud, una respuesta, ningún endpoint que ejecutar por tu parte— y encaja cuando necesitas un solo idioma y puedes esperar ese viaje de ida y vuelta.
Pero el contenido rara vez se publica en un solo idioma. Un módulo de formación llega a 14 idiomas; una entrada de CMS se distribuye a todos los mercados en los que vendes. Si lanzas una llamada síncrona por idioma, te quedas con 14 viajes de ida y vuelta y con la lógica de reintentos cuando uno falla; si esperas una sola llamada síncrona para todos, te bloquea el más lento. Por eso la API también ofrece un modo asíncrono: haces POST de tu contenido una vez con los idiomas de destino, obtienes un 202 al instante y la plataforma traduce cada idioma como un trabajo independiente en segundo plano, encargándose de los reintentos y del aislamiento de fallos mientras tu aplicación sigue respondiendo.
Recurre a async cuando el trabajo sea demasiado grande, demasiado lento o implique demasiados idiomas como para bloquearte. Recurre a sync cuando lo único que necesitas es un par de idiomas en una sola respuesta. Las páginas de async aparecen primero a continuación porque abarcan más, pero ninguna es la API "real": son dos formas de acceder al mismo motor.
Asíncrono: varios idiomas como trabajos#
Una solicitud, todos los idiomas, resultados a medida que estén listos. La API async acepta un único envío, crea un trabajo por cada idioma de destino y entrega cada resultado en cuanto termina —por webhook o WebSocket—, sin bloquear tu aplicación en ningún momento.
Síncrono: una solicitud, una respuesta#
Cuando necesites un par de idiomas y puedas esperar el viaje de ida y vuelta, llama a un endpoint sync y lee el resultado directamente en la respuesta, sin endpoint de webhook ni sondeo.
Siguientes pasos#
Elijas el modo que elijas, el motor que hay detrás lo ajustas tú. Genera una clave y define después qué hace el motor en cada llamada: el modelo que selecciona por idioma y los términos que debe traducir exactamente.
