API de revisão humana
Encontre destinos de documentos com revisão pendente, aprove traduções e envie edições como revisor autorizado.
Uma revisão abrange um documento em um idioma de destino. Ela fica disponível quando há unidades elegíveis prontas para uma decisão na etapa de revisão humana configurada. Configure o roteamento para grupos de decisão antes de iniciar a tarefa.
As solicitações de revisão exigem acesso à organização e permissão para revisar as traduções do engine. As solicitações de decisão também exigem a autenticação de uma pessoa: use o token de acesso da sessão de um revisor ou uma chave de API pessoal. Uma chave de serviço da organização não pode enviar decisões humanas.
Encontrar revisões #
GET /v2/organizations/:orgId/localization/reviews?statuses=open&limit=50A resposta é { "data": [...], "meta": { "nextCursor": "..." } }. Siga os cursores até que nextCursor seja null.
| Campo de consulta | Valores e valor padrão |
|---|---|
statuses | open, completed, timedOut, cancelled; o padrão é open. Repita o parâmetro para informar vários valores. |
order | oldest (padrão) ou newest. |
limit | 1–100; o padrão é 50. |
cursor | Cursor opaco da página anterior. Mantenha os filtros e a ordenação inalterados. |
Consultar estados com decisão tomada exige permissão para gerenciar 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 #
GET /v2/localization/documents/:documentId/targets/:locale/reviewA resposta contém o mesmo contexto do destino e do engine, além de units, informações sobre a transferência de responsabilidade e qualquer pedido externo registrado. takeover é null até que uma pessoa assuma a revisão; externalOrder pode estar ausente ou ser null quando nenhum pedido tiver sido registrado. Cada unidade inclui unitId, key, position, source, value, reference, quality, eligibility, result, decision, reviewerId e decidedAt.
Use sourceText para exibir o texto de origem e valueText para iniciar uma edição. Após uma decisão, exiba settledText: ele contém a edição aceita ou outro resultado definitivo, enquanto valueText mantém a tradução anterior à revisão. Até que um resultado esteja disponível, settledText é igual a valueText.
quality é a saída da etapa de controle de qualidade para a unidade: { "findings": [...] }, conforme descrito na referência do pipeline, ou null quando a etapa não verificou a unidade. eligibility é required, qualityPassed, localeNotCovered ou reused. Apenas as unidades obrigatórias ainda sem decisão precisam de uma decisão humana. As demais fornecem contexto. Um result definitivo e não nulo pode representar um tempo limite esgotado ou um resultado de contingência; examine decision para determinar se uma pessoa aprovou ou editou a unidade.
value é a tradução no ponto de entrada da revisão. Pode ser uma string ou um array de segmentos estruturados de texto, variáveis e marcação. Ao editar, preserve a identidade dos placeholders e o aninhamento.
Aprovar ou editar #
Aprove todas as unidades obrigatórias restantes sem alterações:
POST /v2/localization/documents/:documentId/targets/:locale/review/approve-allEsta solicitação não tem corpo. Para enviar decisões explícitas, faça uma solicitação POST para /decisions com um array não vazio e IDs de unidade únicos:
{
"decisions": [
{ "unitId": "YOUR_FIRST_UNIT_ID", "decision": { "_tag": "Approved" } },
{ "unitId": "YOUR_SECOND_UNIT_ID", "decision": { "_tag": "Edited", "value": "Guardar cambios" } }
]
}Use os IDs da revisão consultada. Para editar um valor estruturado, comece pelo seu valueText e envie o texto editado como Edited.value. Por exemplo, Hello {name}<C1>world</C1><C2/> pode se tornar Bonjour {name}<C1>tout le monde</C1><C2/>. Preserve os tokens dos placeholders, suas quantidades e o aninhamento da marcação; placeholders no mesmo nível podem mudar de posição. Delimitadores literais em texto estruturado são escapados como entidades. A API interpreta esse texto e o converte novamente em segmentos estruturados. Você também pode enviar um array de segmentos estruturados diretamente. Edições de ICU em strings simples devem preservar os casos e as contagens localizados da tradução.
Uma resposta bem-sucedida retorna a revisão atualizada. Revisores internos podem enviar um subconjunto das unidades obrigatórias. As decisões são definitivas. Enquanto o destino ainda aceitar decisões, um envio idêntico feito pelo mesmo revisor reutiliza a decisão salva; uma decisão conflitante é rejeitada. Todo o conjunto enviado é validado antes que qualquer decisão seja gravada.
LocalizationReviewInvalid (422) identifica envios inválidos, incluindo alterações nos placeholders. LocalizationReviewClosed (409) significa que a revisão ou uma unidade não pode mais aceitar essa decisão. Uma nova tentativa após a conclusão do destino pode retornar 409 mesmo que o primeiro envio tenha sido bem-sucedido. Se a resposta se perder, consulte a revisão e compare as decisões salvas e os IDs dos revisores antes de decidir o que ainda precisa ser feito.
Revisão externa e transferência de responsabilidade #
Consulte GET /v2/localization/documents/:documentId/targets/:locale/review/vendor-status para verificar o estado atual do provedor externo: unstarted, inProgress, completed ou unknown.
Para assumir uma revisão externa, é preciso enviar decisões para todas as unidades obrigatórias restantes de uma só vez. Isso encerra a revisão externa e tenta cancelar o pedido do provedor. O trabalho já iniciado ainda pode ser cobrado. O estado do provedor pode mudar entre a consulta e o envio e não garante o cancelamento sem custos.
Aguardar o arquivo final #
O prazo da revisão é expiresAt, calculado a partir de readyAt. Consultas periódicas e novas tentativas não prorrogam esse prazo. Quando ele se esgota, as unidades sem decisão mantêm suas traduções anteriores com avisos; as decisões aceitas permanecem válidas.
Após a revisão, etapas posteriores do pipeline podem alterar o texto. Consulte a tarefa e baixe o destino concluído para obter o arquivo final. Uma revisão concluída não é, por si só, o resultado do download.