API de revisión humana
Busca los destinos de documentos pendientes, aprueba traducciones y envía cambios como revisor autorizado.
Cada revisión abarca un documento en un idioma de destino. Está disponible cuando la etapa de revisión humana configurada tiene unidades aptas para recibir una decisión. Configura el enrutamiento al 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 requieren la intervención de una persona: autentícate con el token de acceso de sesión o la clave de API personal de un revisor. 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 indicar 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. |
Para solicitar estados con una decisión tomada, necesitas permiso para gestionar 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 ha registrado 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. Una vez tomada la 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 de la unidad: { "findings": [...] }, tal como se describe en la referencia de la canalización, o null si el control no la ha comprobado. eligibility es required, qualityPassed, localeNotCovered o reused. Solo las unidades obligatorias que aún no tienen una decisión necesitan una decisión humana. Las demás aportan contexto. Un valor definitivo de result distinto de nulo puede corresponder a un tiempo de espera agotado o a un resultado de respaldo; consulta decision para determinar si una persona ha aprobado o editado la unidad.
value es la traducción en el punto de revisión. Puede ser una cadena o una matriz 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 tomar decisiones explícitas, envía una solicitud POST a /decisions con una matriz no vacía e identificadores 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 identificadores de la revisión obtenida. 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, su número de apariciones y el anidamiento del marcado; los marcadores de posición del mismo nivel pueden cambiar de posición. Los delimitadores literales del texto estructurado se escapan mediante entidades. La API analiza este texto y lo vuelve a convertir en segmentos estructurados. También puedes enviar directamente una matriz de segmentos estructurados. Las ediciones de ICU en cadenas de texto simples deben conservar los casos y los recuentos localizados de la traducción.
Una respuesta correcta 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; una decisión incompatible se rechaza. Se valida todo el conjunto enviado antes de guardar cualquiera de sus decisiones.
LocalizationReviewInvalid (422) identifica los envíos no válidos, incluidos los que contienen marcadores de posición modificados. 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 se haya realizado correctamente. Si se pierde una respuesta, obtén la revisión y compara las decisiones guardadas y los identificadores de los revisores antes de determinar qué queda 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 las decisiones de todas las unidades obligatorias restantes en un único envío. Esto cierra la revisión externa e intenta cancelar el pedido del proveedor. El trabajo ya iniciado puede seguir facturándose. El estado del proveedor puede cambiar entre la consulta y el envío; no garantiza una cancelación gratuita.
Esperar al archivo final #
La fecha límite de la revisión es expiresAt, calculada a partir de readyAt. Las consultas periódicas y los reintentos no la amplían. Al agotarse el tiempo, las unidades sin decisión conservan sus traducciones anteriores con advertencias; las decisiones aceptadas se mantienen.
Tras la revisión, las etapas posteriores de la canalización pueden modificar el texto. Obtén el trabajo y descarga su destino completado para obtener el archivo final. Una revisión completada no es, por sí misma, el resultado de la descarga.