Tu contenido cambia, y ahora tiene que llegar a todos los idiomas en los que publicas. Un módulo de formación recibe una nueva lección. Se guarda una entrada del CMS. Se edita la descripción de un producto. La traducción tiene que desplegarse al alemán, al francés, al japonés y a una docena de idiomas más, y tu aplicación no debería bloquearse mientras eso sucede.
La API de localización asíncrona está pensada precisamente para ese momento: una solicitud, todos los idiomas, resultados a medida que llegan. Haces un único POST con tu contenido y los idiomas de destino, recibes un 202 al instante y la plataforma traduce cada idioma como un trabajo independiente en segundo plano. Mantienes tu glosario, tu voz de marca y la configuración del modelo —el mismo motor que usa la API síncrona— y dejas de tener que encargarte de los reintentos.
En esta página
El problema#
Las plataformas de formación, los sistemas de gestión de contenidos y las herramientas de e-learning suelen necesitar traducir contenido a decenas de idiomas en el momento en que se crea o se actualiza. La API de localización síncrona funciona, pero a escala te obliga a asumir una contrapartida.
Pongamos un módulo de formación redactado en inglés que debe llegar a alumnos en 14 idiomas. Con la API síncrona tienes dos opciones, y ambas tienen un coste:
Lanzar 14 llamadas en paralelo: una solicitud por idioma de destino, cada una con la misma carga útil de origen. Puedes mostrar cada idioma en cuanto vuelve, pero estás gestionando 14 idas y vueltas de red con datos redundantes, y la lógica de reintentos corre de tu cuenta cuando una de ellas falla.
Traducir los 14 en una sola llamada síncrona: menos idas y vueltas, sí, pero entonces tienes que esperar al idioma más lento antes de poder mostrar cualquiera de ellos.
En cualquier caso, tu aplicación queda ocupada mientras se procesan las traducciones. Si tu servidor se reinicia a mitad de proceso, las traducciones en curso se pierden. Si falla un idioma, la gestión de los fallos parciales recae sobre ti. Y ninguna de las dos vías da a tus usuarios una señal clara de que las traducciones están en marcha.
La API asíncrona elimina esa contrapartida. Una solicitud crea un grupo de trabajos con un trabajo por idioma de destino. Cada trabajo se ejecuta de forma independiente a través de tu motor de localización como un flujo de trabajo duradero en segundo plano, así que si tu servidor se reinicia no se pierde nada, porque el trabajo no se está ejecutando dentro de tu proceso. Los resultados se entregan por idioma en cuanto termina cada uno. Tu aplicación sigue respondiendo. Los fallos quedan aislados. La plataforma se encarga de los reintentos y de la entrega.
¿Un solo idioma y puedes esperar un segundo? Usa sync.
La API asíncrona demuestra su valor cuando tienes muchos idiomas, contenido largo o una interfaz que debe mostrar el progreso. Si necesitas un único par de idiomas y puedes esperar una sola ida y vuelta, el endpoint Localize síncrono es la opción más simple: una solicitud, los datos traducidos de vuelta en la respuesta y sin necesidad de mantener un endpoint de webhook. Recurre a async cuando el trabajo es demasiado grande, demasiado lento o implica demasiados idiomas como para bloquearte.
Cómo funciona#
Son tres pasos, y solo el primero ocurre dentro de tu ciclo de solicitud/respuesta. Los otros dos suceden en la plataforma, a su propio ritmo.
Envía una solicitud
Haz un POST de tu contenido y de los idiomas de destino a /jobs/localization. La API valida la carga útil, crea un grupo de trabajos con un trabajo por idioma y devuelve 202 con el ID del grupo y un resumen de los trabajos. Tu aplicación puede continuar de inmediato: no se traduce nada dentro de esta llamada. Consulta Crear trabajos para ver la estructura completa de la solicitud y la respuesta.
La plataforma procesa cada idioma de forma independiente
Cada trabajo se ejecuta a través de tu motor de localización mediante un flujo de trabajo duradero en segundo plano, aplicando la misma selección de modelo, glosario, voz de marca e instrucciones que la API síncrona. Opcionalmente, cada trabajo puede pasar por una pipeline con etapas de preedición, revisión humana, posedición, reformulación y retraducción. Un trabajo pasa de queued a processing hasta alcanzar un estado terminal: completed, completed_with_warnings o failed; y el resultado de un idioma nunca bloquea el de otro.
Recibe los resultados a medida que llegan
En cuanto termina un idioma, la plataforma entrega su resultado a tu URL de webhook. Para mostrar el progreso en tiempo real en tu interfaz —un contador de "3 de 14 listos" que se actualiza a medida que se completan los trabajos—, conéctate al WebSocket del grupo. Si prefieres ir consultando, consulta el grupo periódicamente.
Autenticación
Todas las solicitudes —REST y WebSocket— se autentican con tu cabecera X-API-Key. Las claves tienen alcance a nivel de organización y dan acceso a todos los motores de la organización. Consulta Autenticación para conocer los detalles y Claves API para crear una.
El modelo de grupo de trabajos#
Cada envío genera un grupo que contiene un trabajo por idioma de destino. Esa estructura lo explica todo y es lo que permite responder a las preguntas difíciles.
Un lector escéptico ya estará repasando la lista: ¿qué pasa cuando falla un idioma y qué ocurre con mi aplicación mientras todo esto sigue en curso? El modelo de grupo responde a ambas preguntas.
- Los fallos quedan aislados, porque cada idioma tiene su propio trabajo. Si el alemán se completa correctamente y el japonés falla, la traducción al alemán se entrega con normalidad y el trabajo de japonés lleva su propio
errorMessage. El grupo informa departial, y el trabajo que sí ha salido bien sigue adelante. Un fallo en un idioma no puede deshacer otro que ya se ha completado. La semántica completa de estados está en Seguir un grupo de trabajos. - El trabajo en curso sobrevive a un reinicio, porque no se ejecuta dentro de tu proceso. Cada trabajo es un flujo de trabajo duradero en segundo plano en la plataforma. Si tu servidor se reinicia, no se pierde nada de lo que estaba en marcha: vuelves a conectarte o consultas, y el grupo está exactamente donde lo dejaste.
- El grupo es un modelo de progreso que puedes conectar a una interfaz. Guarda el
groupIddel202y luego alimenta un indicador de progreso a partir de las entregas por webhook o de las instantáneas de WebSocket. "3 de 14 idiomas listos" es un contador sobre los trabajos hijo del grupo.
El coste real de este modelo es sencillo: asumes una pequeña integración que la llamada síncrona no te exige. Para recibir resultados, debes mantener un endpoint HTTPS de webhook o un WebSocket del lado del servidor, y gestionar cada idioma a medida que llega en lugar de leer los datos traducidos directamente de una sola respuesta. A cambio, la plataforma se encarga de los reintentos, del aislamiento de fallos y de la entrega, y tu aplicación nunca se bloquea por una traducción.
Ese es el intercambio para el que está diseñada la API asíncrona: una solicitud, todos los idiomas, resultados a medida que llegan. Las siguientes páginas son los verbos de esa frase.
