Crea un flujo de trabajo con la API de traducción
Traduce los registros de tu aplicación en el servidor y mantén las versiones aceptadas en cada idioma vinculadas a la revisión del original a la que corresponden.
Cuando alguien modifica la descripción de un producto, cada versión traducida debe reflejar ese cambio. La respuesta de la API proporciona el nuevo texto; tu aplicación decide a qué registro pertenece, si el original sigue vigente y cuándo pueden verlo los lectores.
Esta guía convierte una primera solicitud de traducción en un flujo de trabajo repetible en el servidor. Es adecuado para registros que gestiona tu aplicación, como descripciones de productos y artículos de ayuda. Los recursos estáticos de la aplicación suelen encajar mejor en un flujo de trabajo de archivos en CI, porque la compilación de recursos y la revisión del repositorio ya ofrecen un punto en el que validarlos.
Envía un bloque de contenido coherente #
Crea una tarea de localización con un único documento JSON incluido directamente en la solicitud para un registro de producto. Agrupa los campos relacionados para que el contexto permita describir su función y conserva claves estables para que el objeto descargado se corresponda con esos campos.
Envía este cuerpo a POST /v2/organizations/:orgId/localization/jobs, con una clave de API y un Idempotency-Key estable para esta revisión:
{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"documents": [
{
"key": "products/bottle.json",
"format": {
"type": "json",
"options": {
"context": "Product listing for a reusable drinks bottle",
"hints": {
"$.title": ["Catalog card title"],
"$.description": ["Short product description; do not add specifications"]
}
}
},
"source": {
"content": {
"title": "Insulated bottle",
"description": "Keeps drinks cold during your commute."
}
}
}
]
}Guarda las credenciales en el servidor y selecciona el motor de forma explícita. Usa las pautas del glosario compartido para la terminología del producto y el contexto del documento para este uso concreto. La Referencia de JSON explica las indicaciones contextuales y las rutas protegidas.
Ejecuta la traducción en segundo plano #
Guarda el ID de la tarea devuelto antes de iniciarla. Sube todo lo que figure en uploads y, después, llama a POST /v2/localization/jobs/:id/start. Incluso el JSON incluido directamente en la solicitud necesita este inicio explícito.
Consulta periódicamente la tarea desde el proceso de trabajo del servidor y descarga las traducciones de destino completadas mediante las URL devueltas. La solicitud de guardado del editor puede recibir una respuesta en cuanto tu aplicación haya puesto este trabajo en cola de forma persistente. No necesita permanecer abierta mientras se realiza la traducción o la revisión humana.
Para las actualizaciones incrementales, conserva los archivos anteriores del original y de las traducciones aceptadas e inclúyelos en la siguiente solicitud de documento. Actualizaciones de documentos explica los límites de la reutilización.
Registra el trabajo después de guardar el original #
Una vez confirmada la transacción del original, crea un registro de trabajo en tu propio almacenamiento con el ID del contenido, la revisión del original, el idioma de destino, el registro del motor de localización o de su configuración y el estado de procesamiento. Pon la traducción en cola a partir de ese registro. Así evitarás que un proceso de trabajo traduzca una modificación que la transacción del original revierta más adelante.
Conserva un resultado por idioma de destino. La traducción al alemán puede estar lista mientras la francesa necesita un reintento o una revisión. Registrar un único indicador global de «traducido» ocultaría esa diferencia a la aplicación que decide qué mostrar. Los nombres de estado que añadas forman parte del diseño de tu aplicación, no del vocabulario de respuesta de la API.
Acepta resultados solo para la revisión prevista #
Las modificaciones del original y las traducciones completadas pueden llegar en distinto orden. Considera esta secuencia:
| Evento | Acción de la aplicación |
|---|---|
| Se guarda la revisión 12 | Pon la revisión 12 en cola para traducirla al alemán. |
| Se guarda la revisión 13 antes de que termine ese trabajo | Pon la revisión 13 en cola y márcala como el original vigente. |
| Termina la traducción de la revisión 13 | Valídala y acéptala para la revisión 13. |
| La traducción de la revisión 12 termina más tarde | Conserva el resultado registrado sin sustituir el texto aceptado de la revisión 13. |
En el momento de la activación, compara la revisión del original que figura en el registro de trabajo con el original vigente. En tu sistema de almacenamiento, realiza la comparación y condiciona la escritura a esa revisión, de modo que no pueda producirse otra modificación del original entre ambas operaciones sin que se detecte. Si el trabajo correspondiente a la revisión vigente no se puso en cola o falló, programa esa revisión en lugar de reasignar un resultado anterior.
Al leer los datos, solicita la traducción aceptada para el idioma y la revisión solicitados. Decide qué hará la aplicación si no existe: mostrar el texto original, usar un idioma alternativo designado, mostrar una traducción anterior cuyo uso se registre explícitamente o dejar la publicación en espera. La elección adecuada depende de lo que un texto desactualizado o sin traducir pueda suponer para quien lo lea. Un cambio en una condición del proceso de compra puede justificar una política más estricta que una descripción de producto informal.
Recupera el trabajo con la identidad remota y el registro local #
Guarda de forma persistente la clave de idempotencia de la solicitud antes de enviarla y su ID de tarea en cuanto recibas la respuesta de creación. Si se agota el tiempo de espera de la red, repite la solicitud de creación sin cambios con esa clave o recupera la tarea registrada. Repetir la llamada de inicio actúa sobre la misma tarea.
Tras fallos temporales de lectura, consulta periódicamente con intervalos de espera crecientes. El tiempo límite del cliente pone fin a la espera, no al trabajo del servidor. Conserva por separado los resultados completados de los idiomas de destino y los detalles de los que hayan fallado; una tarea fallida aún puede contener archivos completados que se puedan utilizar.
Los errores de autenticación, los motores desactivados, los datos de entrada no válidos y los límites de la cuenta requieren medidas correctivas. Una tarea pendiente puede iniciarse de nuevo una vez resuelto el límite de admisión. Si el trabajo ha fallado durante la ejecución, corrige la causa y envía los documentos o idiomas afectados con una nueva clave de idempotencia.
Al aceptar los resultados, aplica la misma comprobación de revisión a cada uno, incluidos los recuperados tras una incidencia. Que la descarga haya finalizado confirma que el texto está disponible; tu política de validación y revisión determina si puede publicarse.
Prueba el ciclo de vida del registro #
Usa un registro breve con una variable y, después, prueba una actualización del original, un fallo en un idioma y traducciones que se completen fuera de orden. Comprueba las claves de los campos almacenados y los identificadores de idioma, además del texto. La aplicación debe mostrar solo la versión que acepte tu política, y quien la revise debe poder rastrearla hasta su original.
Para medir la calidad, conserva el original y la traducción emparejados junto con el criterio utilizado para evaluarlos. El diseño de mediciones se aplica de forma independiente al flujo de trabajo de generación. Así, tu registro podrá distinguir entre el texto devuelto, una respuesta de medición, la aceptación humana y la publicación, en lugar de tratarlos como un único evento.