API de revisão humana

Encontre traduções de documentos pendentes de revisão, aprove-as e envie alterações como revisor autorizado.

Cada revisão abrange um documento num único idioma de destino. Fica disponível quando a etapa de revisão humana configurada tem unidades elegíveis prontas para uma decisão. Configure o encaminhamento para grupos de decisão antes de iniciar a tarefa.

Os pedidos de revisão exigem acesso à organização e permissão para rever as traduções do motor. Os pedidos de decisão exigem também a identificação de uma pessoa: autentique-se com o token de acesso da sessão de um revisor ou com a respetiva chave de API pessoal. Uma chave de serviço da organização não pode enviar decisões humanas.

Encontrar revisões #

http
GET /v2/organizations/:orgId/localization/reviews?statuses=open&limit=50

A resposta é { "data": [...], "meta": { "nextCursor": "..." } }. Siga os cursores até que nextCursor seja null.

Campo de consultaValores e valor predefinido
statusesopen, completed, timedOut, cancelled; o valor predefinido é open. Repita o parâmetro para indicar vários valores.
orderoldest (predefinido) ou newest.
limit1–100; o valor predefinido é 50.
cursorCursor opaco da página anterior. Mantenha os filtros e a ordenação inalterados.

A consulta de estados com decisão tomada exige permissão para gerir as revisões da organização. Cada resumo identifica documentId, locale, jobId, engineId, engineName, documentKey, sourceLocale, provider, vendorStartedAt, status, readyAt, expiresAt, closedAt, totalUnits e pendingUnits.

Consultar uma revisão #

http
GET /v2/localization/documents/:documentId/targets/:locale/review

A resposta contém o mesmo contexto do destino e do motor, além de units, informações sobre a tomada de controlo e qualquer encomenda externa registada. takeover é null até que uma pessoa assuma o controlo; externalOrder pode estar ausente ou ser null quando não tiver sido registada nenhuma encomenda. Cada unidade inclui unitId, key, position, source, value, reference, quality, eligibility, result, decision, reviewerId e decidedAt.

Utilize sourceText para apresentar o texto de origem e valueText para iniciar uma edição. Após uma decisão, apresente settledText: contém a alteração aceite ou outro resultado definitivo, enquanto valueText mantém a tradução anterior à revisão. Enquanto não houver um resultado disponível, settledText é igual a valueText.

quality é o resultado do controlo de qualidade para a unidade: { "findings": [...] }, conforme descrito na referência do fluxo de processamento, ou null quando o controlo não verificou a unidade. eligibility é required, qualityPassed, localeNotCovered ou reused. Só as unidades obrigatórias ainda sem decisão precisam de uma decisão humana. As restantes fornecem contexto. Um valor definitivo de result diferente de nulo pode representar um tempo limite excedido ou uma solução de recurso; consulte decision para determinar se uma pessoa aprovou ou editou a unidade.

value é a tradução no momento em que entra em revisão. Pode ser uma cadeia de texto ou uma matriz de segmentos estruturados de texto, variáveis e marcação. Ao editar, preserve a identidade dos marcadores de posição e o respetivo aninhamento.

Aprovar ou editar #

Aprove todas as unidades obrigatórias restantes sem alterações:

http
POST /v2/localization/documents/:documentId/targets/:locale/review/approve-all

Este pedido não tem corpo. Para enviar decisões explícitas, envie um pedido POST para /decisions com uma matriz não vazia e IDs de unidade únicos:

json
{
  "decisions": [
    { "unitId": "YOUR_FIRST_UNIT_ID", "decision": { "_tag": "Approved" } },
    { "unitId": "YOUR_SECOND_UNIT_ID", "decision": { "_tag": "Edited", "value": "Guardar cambios" } }
  ]
}

Utilize os IDs da revisão obtida. Para editar um valor estruturado, parta do respetivo valueText e envie o texto editado como Edited.value. Por exemplo, Hello {name}<C1>world</C1><C2/> pode passar a Bonjour {name}<C1>tout le monde</C1><C2/>. Preserve os tokens dos marcadores de posição, as respetivas contagens e o aninhamento da marcação; os marcadores de posição do mesmo nível podem mudar de posição. Os delimitadores literais no texto estruturado são codificados como entidades. A API analisa este texto e volta a convertê-lo em segmentos estruturados. Também pode enviar diretamente uma matriz de segmentos estruturados. As edições de ICU em cadeias de texto simples têm de preservar os casos e as contagens localizados da tradução.

Uma resposta bem-sucedida devolve a revisão atualizada. Os revisores internos podem enviar um subconjunto das unidades obrigatórias. As decisões são definitivas. Enquanto o destino aceitar decisões, um envio idêntico pelo mesmo revisor reutiliza a decisão guardada; uma decisão em conflito é rejeitada. O conjunto enviado é validado na íntegra antes de se guardar qualquer uma das suas decisões.

LocalizationReviewInvalid (422) identifica envios inválidos, incluindo alterações aos marcadores de posição. LocalizationReviewClosed (409) significa que a revisão ou uma unidade já não pode aceitar essa decisão. Uma nova tentativa após a conclusão do destino pode devolver 409, mesmo que o primeiro envio tenha sido bem-sucedido. Se uma resposta se perder, obtenha a revisão e compare as decisões guardadas e os IDs dos revisores antes de decidir o que falta fazer.

Revisão externa e tomada de controlo #

Consulte GET /v2/localization/documents/:documentId/targets/:locale/review/vendor-status para saber o estado atual do fornecedor externo: unstarted, inProgress, completed ou unknown.

Para assumir o controlo de uma revisão externa, tem de enviar decisões para todas as unidades obrigatórias restantes de uma só vez. Esta ação encerra a revisão externa e tenta cancelar a encomenda ao fornecedor. O trabalho já iniciado poderá ainda ser cobrado. O estado do fornecedor pode mudar entre a consulta e o envio e não garante um cancelamento sem custos.

Aguardar o ficheiro final #

O prazo da revisão é expiresAt, calculado a partir de readyAt. As consultas periódicas e as novas tentativas não o prolongam. Quando o prazo expira, as unidades sem decisão mantêm as traduções anteriores, com avisos; as decisões aceites mantêm-se.

Após a revisão, as etapas seguintes do fluxo de processamento podem alterar o texto. Obtenha a tarefa e transfira o respetivo destino concluído para obter o ficheiro final. Uma revisão concluída não é, por si só, o resultado a transferir.