API de revisión humana
Encuentra los destinos de documentos pendientes, aprueba traducciones y envía cambios como revisor autorizado.
Una revisión abarca un documento en un idioma de destino. Está disponible cuando la etapa de revisión humana configurada tiene unidades aptas listas para recibir una decisión. Configura el enrutamiento del grupo de decisión antes de iniciar el trabajo.
Las solicitudes de revisión requieren acceso a la organización y permiso para revisar las traducciones del motor. Las solicitudes de decisión también deben provenir de una persona: autentícate con el token de acceso de sesión de un revisor o con su clave de API personal. Una clave de servicio de la organización no puede enviar decisiones humanas.
Buscar revisiones #
GET /v2/organizations/:orgId/localization/reviews?statuses=open&limit=50La respuesta es { "data": [...], "meta": { "nextCursor": "..." } }. Sigue los cursores hasta que nextCursor sea null.
| Campo de consulta | Valores y valor predeterminado |
|---|---|
statuses | open, completed, timedOut, cancelled; el valor predeterminado es open. Repite el parámetro para usar varios valores. |
order | oldest (predeterminado) o newest. |
limit | 1–100; el valor predeterminado es 50. |
cursor | Cursor opaco de la página anterior. Mantén los filtros y el orden sin cambios. |
Consultar estados con decisiones ya tomadas requiere permiso para administrar las revisiones de la organización. Cada resumen identifica documentId, locale, jobId, engineId, engineName, documentKey, sourceLocale, provider, vendorStartedAt, status, readyAt, expiresAt, closedAt, totalUnits y pendingUnits.
Consultar una revisión #
GET /v2/localization/documents/:documentId/targets/:locale/reviewLa respuesta contiene el mismo contexto del destino y del motor, además de units, información sobre la toma de control y cualquier pedido externo registrado. takeover es null hasta que una persona toma el control; externalOrder puede estar ausente o ser null si no se registró ningún pedido. Cada unidad incluye unitId, key, position, source, value, reference, quality, eligibility, result, decision, reviewerId y decidedAt.
Usa sourceText para mostrar el texto de origen y valueText para iniciar una edición. Después de una decisión, muestra settledText: contiene la edición aceptada u otro resultado definitivo, mientras que valueText conserva la traducción anterior a la revisión. Hasta que haya un resultado disponible, settledText es igual a valueText.
quality es el resultado del control de calidad para la unidad: { "findings": [...] }, como se describe en la referencia del flujo de procesamiento, o null si el control no la verificó. eligibility es required, qualityPassed, localeNotCovered o reused. Solo las unidades obligatorias aún sin decidir necesitan una decisión humana. Las demás aportan contexto. Un valor definitivo de result que no sea nulo puede indicar que se agotó el tiempo de espera o que se recurrió a una alternativa de respaldo; consulta decision para determinar si una persona aprobó o editó la unidad.
value es la traducción en el punto de revisión. Puede ser una cadena o un arreglo de segmentos estructurados de texto, variables y marcado. Al editar, conserva la identidad de los marcadores de posición y su anidamiento.
Aprobar o editar #
Aprueba todas las unidades obligatorias restantes sin cambios:
POST /v2/localization/documents/:documentId/targets/:locale/review/approve-allEsta solicitud no tiene cuerpo. Para enviar decisiones explícitas, envía una solicitud POST a /decisions con un arreglo no vacío e IDs de unidad únicos:
{
"decisions": [
{ "unitId": "YOUR_FIRST_UNIT_ID", "decision": { "_tag": "Approved" } },
{ "unitId": "YOUR_SECOND_UNIT_ID", "decision": { "_tag": "Edited", "value": "Guardar cambios" } }
]
}Usa los IDs de la revisión recuperada. Para editar un valor estructurado, parte de su valueText y envía el texto editado como Edited.value. Por ejemplo, Hello {name}<C1>world</C1><C2/> puede convertirse en Bonjour {name}<C1>tout le monde</C1><C2/>. Conserva los tokens de los marcadores de posición, sus cantidades y el anidamiento del marcado; los marcadores de posición del mismo nivel pueden cambiar de lugar. Los delimitadores literales del texto estructurado se escapan mediante entidades. La API analiza este texto y lo convierte de nuevo en segmentos estructurados. También puedes enviar directamente un arreglo de segmentos estructurados. Las ediciones de ICU en cadenas de texto simples deben conservar los casos y las cantidades localizados de la traducción.
Una respuesta exitosa devuelve la revisión actualizada. Los revisores internos pueden enviar un subconjunto de las unidades obligatorias. Las decisiones son definitivas. Mientras el destino siga aceptando decisiones, un envío idéntico del mismo revisor reutiliza la decisión guardada; si la decisión entra en conflicto con la guardada, se rechaza. Se valida todo el conjunto enviado antes de guardar cualquiera de sus decisiones.
LocalizationReviewInvalid (422) identifica envíos no válidos, incluidos los que modifican marcadores de posición. LocalizationReviewClosed (409) significa que la revisión o una unidad ya no puede aceptar esa decisión. Un reintento después de que se complete el destino puede devolver 409 aunque el primer envío haya tenido éxito. Si se pierde una respuesta, recupera la revisión y compara sus decisiones guardadas y los IDs de los revisores antes de determinar qué falta por hacer.
Revisión externa y toma de control #
Consulta GET /v2/localization/documents/:documentId/targets/:locale/review/vendor-status para conocer el estado actual del proveedor externo: unstarted, inProgress, completed o unknown.
Para tomar el control de una revisión externa, debes enviar decisiones para todas las unidades obligatorias restantes en un solo envío. Esto cierra la revisión externa e intenta cancelar el pedido del proveedor. El trabajo ya iniciado puede generar cargos. El estado del proveedor puede cambiar entre la consulta y el envío; no garantiza una cancelación sin costo.
Esperar el archivo final #
El plazo de la revisión vence en expiresAt, calculado a partir de readyAt. Las consultas periódicas y los reintentos no lo extienden. Cuando se agota el tiempo, las unidades aún sin decidir conservan sus traducciones anteriores con advertencias; las decisiones aceptadas se mantienen.
Después de la revisión, las etapas posteriores del flujo de procesamiento pueden cambiar el texto. Recupera el trabajo y descarga su destino completado para obtener el archivo final. Una revisión completada no constituye, por sí sola, el resultado de la descarga.