Tienes contenido en un idioma y usuarios que leen en muchos otros. La API existe para cerrar esa brecha de forma programática: envías texto, lo recibes de vuelta traducido, y cada traducción pasa por un motor de localización que configuras una sola vez. El motor aplica tu glosario, voz de marca, instrucciones y selección de modelo por idioma en cada llamada, para que el resultado suene como tu equipo decidió que debe sonar, y no como lo estimó un modelo genérico.
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 app sigue respondiendo. Esta página cubre la URL base, esa decisión y a dónde ir después.
Lo que asume esta API
Esta es la referencia para traducir de forma programática. Parte de que ya decidiste localizar desde tu propio código o pipeline —no desde el panel— y que ya tienes una clave de API. ¿Recién llegas a la plataforma? El concepto de motor de localización es lo primero que debes 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 viven bajo un mismo host:
https://api.lingo.devCada solicitud también incluye un encabezado, X-API-Key. La clave está asociada a la organización y solo se muestra una vez al crearse; las reglas completas para enviarla están en Authentication, y lo que devuelve la API cuando una solicitud es rechazada está en Errors and status codes.
Dos formas de traducir#
Detrás de ambos modos está el mismo motor, con el mismo glosario y la misma voz de marca. Lo único que cambia es quién se hace cargo de 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 simple: una solicitud, una respuesta, sin ningún endpoint que tengas que ejecutar de tu lado; y es la indicada 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 capacitación llega a 14 idiomas; una entrada de CMS se distribuye a todos los mercados en los que vendes. Si haces una llamada síncrona por idioma, te haces cargo de 14 viajes de ida y vuelta y de la lógica de reintentos cuando uno falla; si esperas una sola llamada síncrona para todos, quedas bloqueado por el más lento. Por eso, la API también ofrece un modo asíncrono: haces POST de tu contenido una sola vez con los idiomas de destino, recibes un 202 de inmediato, 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 app sigue respondiendo.
Elige async cuando el trabajo sea demasiado grande, demasiado lento o abarque demasiados idiomas como para bloquearte. Elige sync cuando lo único que necesites sea un par de idiomas en una sola respuesta. Las páginas de async aparecen primero abajo porque cubren más, pero ninguna es la API "real": son dos formas del mismo motor.
Asíncrono: varios idiomas como trabajos#
Una solicitud, todos los idiomas, resultados en cuanto van quedando listos. La API asíncrona recibe un solo envío, crea un trabajo por cada idioma de destino y entrega cada resultado en el momento en que termina —por webhook o WebSocket— sin que tu app se bloquee por nada de eso.
Síncrono: una solicitud, una respuesta#
Cuando necesitas un par de idiomas y puedes esperar el viaje de ida y vuelta, llama a un endpoint síncrono y lee el resultado directamente en la respuesta, sin endpoint de webhook ni polling.
Siguientes pasos#
Elijas el modo que elijas, el motor que está detrás es tuyo para ajustarlo. Genera una clave y luego define lo que hace el motor en cada llamada: el modelo que selecciona por idioma y los términos que debe traducir exactamente.
