Crea un flujo de trabajo de traducción con la API

Traduce los registros de tu aplicación en el servidor y mantén cada versión aceptada en su idioma vinculada a la revisión de origen que describe.

Cuando alguien edita la descripción de un producto, cada versión traducida debe reflejar ese cambio. La respuesta de la API proporciona el texto nuevo; tu aplicación decide a qué registro pertenece, si el contenido de origen sigue vigente y cuándo pueden verlo los lectores.

Esta guía lleva una primera solicitud de traducción a un flujo de trabajo de backend que puedes ejecutar de forma repetible. Es adecuado para registros que administra tu aplicación, como descripciones de productos y entradas de ayuda. Para los recursos estáticos de la aplicación, suele funcionar mejor un flujo de trabajo de archivos en CI, ya que la compilación de recursos y la revisión del repositorio ofrecen un punto donde validarlos.

Envía una unidad de contenido coherente #

Crea un trabajo de localización con un único documento JSON en línea para un registro de producto. Agrupa los campos relacionados para que el contexto describa su propósito y conserva claves estables para que el objeto descargado corresponda a esos mismos 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:

json
{
  "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."
        }
      }
    }
  ]
}

Mantén las credenciales en el backend 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 específico. La Referencia de JSON explica las indicaciones y las rutas protegidas.

Ejecuta la traducción en segundo plano #

Guarda el ID del trabajo que recibas antes de iniciarlo. Sube todo lo que se indique en uploads y luego llama a POST /v2/localization/jobs/:id/start. Incluso el JSON en línea requiere este inicio explícito.

Consulta periódicamente el estado del trabajo desde el proceso de trabajo del backend y descarga los resultados completados de los idiomas de destino mediante las URL recibidas. La solicitud de guardado de quien edita puede recibir una respuesta en cuanto tu aplicación haya dejado este trabajo en una cola persistente. No tiene que permanecer abierta mientras se realiza la traducción o la revisión humana.

Para las actualizaciones incrementales, conserva los artefactos de origen anteriores y los de destino aceptados, y proporciónalos 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 contenido de origen #

Una vez confirmada la transacción del contenido de origen, crea un registro de trabajo en tu propio almacenamiento con el ID del contenido, la revisión de origen, el idioma de destino, el registro del motor de localización o de su configuración y el estado de procesamiento. Agrega la traducción a la cola a partir de ese registro. Así evitas que un proceso de trabajo traduzca una edición que la transacción de origen revierta después.

Conserva un resultado por idioma de destino. El alemán puede estar listo mientras que el francés necesita un reintento o una revisión. Registrar una sola marca general de “traducido” ocultaría esa diferencia a la aplicación que decide qué mostrar. Los nombres de estado que agregues corresponden al diseño de tu aplicación, no al vocabulario de respuesta de la API.

Acepta el resultado solo para la revisión prevista #

Las ediciones del contenido de origen y las traducciones completadas pueden llegar en distinto orden. Considera esta secuencia:

EventoAcción de la aplicación
Se guarda la revisión 12Agrega la revisión 12 a la cola para traducirla al alemán.
Se guarda la revisión 13 antes de que termine ese trabajoAgrega la revisión 13 a la cola y márcala como el contenido de origen vigente.
Finaliza la traducción de la revisión 13Valídala y acéptala para la revisión 13.
La traducción de la revisión 12 finaliza despuésConserva su resultado registrado sin reemplazar el texto aceptado de la revisión 13.

Al activar el resultado, compara la revisión de origen del registro de trabajo con la del contenido de origen vigente. Realiza la comparación y la escritura condicionada a esa revisión en tu sistema de almacenamiento, de modo que ninguna edición del contenido de origen pase inadvertida entre ambas operaciones. Si el trabajo de la revisión vigente no se agregó a la cola o falló, programa esa revisión en lugar de cambiarle la etiqueta a un resultado anterior.

Al leer los datos, solicita la traducción aceptada para el idioma y la revisión requeridos. Decide qué hará la aplicación si esa traducción no existe: mostrar el texto de origen, usar un idioma alternativo designado, mostrar una traducción anterior registrada explícitamente o suspender la publicación. La elección adecuada depende de lo que un texto desactualizado o sin traducir pueda significar para quien lo lee. Un cambio en una condición del checkout puede requerir una política más estricta que una descripción informal de un producto.

Recupera el trabajo con la identidad remota y el registro local #

Guarda de forma persistente la clave de idempotencia antes de enviar la solicitud y el ID del trabajo 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 el trabajo registrado. Repetir el inicio actúa sobre el mismo trabajo.

Después de fallos temporales de lectura, consulta el estado con intervalos de espera crecientes. Cuando vence el plazo del cliente, este deja de esperar, pero el trabajo del servidor continúa. Conserva por separado los resultados completados de los idiomas de destino y los detalles de los que fallaron; un trabajo fallido aún puede contener archivos completados que se pueden usar.

Los errores de autenticación, los motores deshabilitados, los datos de entrada no válidos y los límites de la cuenta requieren corrección. Un trabajo pendiente puede iniciarse de nuevo después de resolver el límite de admisión. Si un trabajo falló 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 verificación de revisión a todos, incluidos los que obtengas tras recuperar el trabajo. Una descarga completada 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 luego prueba una actualización del contenido de origen, un fallo en un idioma y traducciones que se completen fuera de orden. Revisa las claves de campo almacenadas 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 origen.

Para medir la calidad, conserva el par de contenido de origen y de destino junto con el criterio usado para examinarlos. Diseño de mediciones se aplica de forma independiente al flujo de trabajo de generación. Así, tu registro puede distinguir entre el texto recibido, una respuesta de medición, la aceptación humana y la publicación, en lugar de tratarlos como un solo evento.