Tu contenido cambia, y ahora tiene que llegar a todos los idiomas en los que publicas. Un módulo de capacitación recibe una lección nueva. Se guarda una entrada en el CMS. Se edita la descripción de un producto. La traducción tiene que extenderse al alemán, francés, japonés y una docena más, y tu app no debería bloquearse mientras eso pasa.
La API de localización asíncrona está hecha justo para ese momento: una sola solicitud, todos los idiomas, resultados a medida que van llegando. Haces un POST de tu contenido una vez con los idiomas de destino, recibes un 202 de inmediato y la plataforma traduce cada idioma como un trabajo independiente en segundo plano. Mantienes tu glosario, voz de marca y configuración del modelo —el mismo motor que usa la API síncrona— y dejas de hacerte cargo de los reintentos.
En esta página
El problema#
Las plataformas de capacitación, los sistemas de gestión de contenido y las herramientas de e-learning suelen necesitar traducir contenido a decenas de idiomas en el momento en que se crea o actualiza. La API de localización síncrona funciona, pero a escala te obliga a hacer una concesión.
Pensemos en un módulo de capacitación escrito en inglés que tiene que llegar a estudiantes en 14 idiomas. Con la API síncrona tienes dos opciones, y ambas tienen un costo:
Lanzar 14 llamadas en paralelo: una solicitud por cada idioma de destino, cada una con la misma carga útil de origen. Puedes mostrar cada idioma en cuanto regresa, pero estás administrando 14 viajes de ida y vuelta por red con datos redundantes, y si uno falla, los reintentos quedan por tu cuenta.
Traducir los 14 en una sola llamada síncrona: menos viajes de ida y vuelta, pero ahora tienes que esperar al idioma más lento antes de poder mostrar cualquiera de los demás.
En ambos casos, tu aplicación queda ocupada mientras se procesan las traducciones. Si tu servidor se reinicia a mitad del proceso, las traducciones en curso se pierden. Si falla un idioma, el manejo de fallas parciales queda de tu lado. Y ninguna de las dos opciones les da a tus usuarios una señal clara de que las traducciones están en marcha.
La API asíncrona elimina esa concesión. Una sola solicitud crea un grupo de trabajos con un trabajo por cada 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 corre dentro de tu proceso. Los resultados se entregan por idioma en cuanto termina cada uno. Tu app sigue respondiendo. Las fallas quedan aisladas. La plataforma se encarga de los reintentos y de la entrega.
¿Solo un idioma y puedes esperar un segundo? Usa sync.
La API asíncrona demuestra su valor cuando tienes muchos idiomas, contenido largo o una UI que debería mostrar el progreso. Si necesitas un solo par de idiomas y puedes esperar un viaje de ida y vuelta, el endpoint Localize síncrono es la opción más simple: una solicitud, los datos traducidos en la respuesta y ningún endpoint de webhook que mantener. Recurre a async cuando el trabajo sea demasiado grande, demasiado lento o involucre 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 ocurren en la plataforma, a su propio ritmo.
Envía una sola solicitud
Haz un POST de tu contenido y 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 trabajos. Tu aplicación puede seguir 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 pasa por 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 un pipeline con etapas de preedición, revisión humana, posedición, reformulación y retrotraducción. Un trabajo pasa de queued a processing hasta llegar a un estado terminal: completed, completed_with_warnings o failed; y el resultado de un idioma nunca bloquea el de otro.
Recibe resultados a medida que van llegando
En cuanto termina un idioma, la plataforma entrega su resultado a tu URL de webhook. Si quieres mostrar progreso en vivo en tu UI —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 consultar, consulta el grupo a intervalos.
Autenticación
Cada solicitud —REST y WebSocket— se autentica con tu encabezado X-API-Key. Las claves tienen alcance a nivel de organización y llegan a todos los motores de la organización. Consulta Authentication para ver los detalles, y API Keys para crear una.
El modelo de grupo de trabajos#
Cada envío produce un grupo que contiene un trabajo por cada idioma de destino. Esa estructura es todo el modelo mental, y es lo que hace que las preguntas difíciles tengan respuesta.
Un lector escéptico ya se estará haciendo la lista: ¿qué pasa si falla un idioma y qué pasa con mi app mientras todo esto sigue en curso? El modelo de grupo responde ambas preguntas.
- Las fallas quedan aisladas, porque cada idioma tiene su propio trabajo. Si el alemán se completa con éxito y el japonés falla, la traducción al alemán se entrega normalmente y el trabajo de japonés conserva su propio
errorMessage. El grupo reportapartial, y el trabajo que sí salió bien igual se publica. Una falla en un idioma no puede revertir otro que ya se completó. La semántica completa de estados está en Rastrear 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 dentro de la plataforma. Si tu servidor se reinicia, no se pierde nada de lo que estaba en progreso: te vuelves a conectar o consultas, y el grupo está exactamente donde lo dejaste.
- El grupo es un modelo de progreso que puedes conectar a una UI. Guarda el
groupIdde la202y luego alimenta un indicador de progreso con entregas por webhook o snapshots de WebSocket. "3 de 14 idiomas listos" es un contador sobre los trabajos hijos del grupo.
El costo real de este modelo es que asumes una pequeña integración adicional que la llamada síncrona no te exige. Para recibir resultados, ejecutas un endpoint HTTPS de webhook o mantienes un WebSocket del lado del servidor, y manejas 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 fallas y de la entrega, y tu app nunca se bloquea por una traducción.
Ese es el intercambio para el que está diseñada la API asíncrona: una sola solicitud, todos los idiomas, resultados a medida que van llegando. Las páginas que siguen son los verbos de esa oración.
