API de relecture humaine
Trouvez les documents cibles en attente, approuvez les traductions et soumettez des modifications en tant que personne autorisée à effectuer la relecture.
Une relecture porte sur un document dans une langue cible. Elle devient disponible lorsque l’étape de relecture humaine configurée contient des unités admissibles prêtes à faire l’objet d’une décision. Configurez le routage vers les groupes de décision avant de lancer la tâche.
Les requêtes de relecture nécessitent un accès à l’organisation et l’autorisation de relire les traductions du moteur. Les requêtes de décision doivent également être authentifiées au nom d’une personne : utilisez le jeton d’accès de session ou la clé API personnelle d’une personne chargée de la relecture. Une clé de service de l’organisation ne permet pas de soumettre de décisions humaines.
Rechercher des demandes de relecture #
GET /v2/organizations/:orgId/localization/reviews?statuses=open&limit=50La réponse est { "data": [...], "meta": { "nextCursor": "..." } }. Suivez les curseurs jusqu’à ce que nextCursor soit null.
| Champ de requête | Valeurs et valeur par défaut |
|---|---|
statuses | open, completed, timedOut, cancelled ; valeur par défaut : open. Répétez le paramètre pour spécifier plusieurs valeurs. |
order | oldest (par défaut) ou newest. |
limit | 1–100 ; valeur par défaut : 50. |
cursor | Curseur opaque de la page précédente. Conservez les mêmes filtres et le même ordre. |
Pour demander les statuts correspondant à des décisions déjà prises, vous devez disposer de l’autorisation de gérer la relecture au sein de l’organisation. Chaque résumé identifie documentId, locale, jobId, engineId, engineName, documentKey, sourceLocale, provider, vendorStartedAt, status, readyAt, expiresAt, closedAt, totalUnits et pendingUnits.
Lire une demande de relecture #
GET /v2/localization/documents/:documentId/targets/:locale/reviewLa réponse contient le même contexte relatif à la cible et au moteur, ainsi que units, les informations de reprise en main et toute commande externe enregistrée. takeover vaut null jusqu’à ce qu’une personne reprenne la main ; externalOrder peut être absent ou valoir null lorsqu’aucune commande n’a été enregistrée. Chaque unité comprend unitId, key, position, source, value, reference, quality, eligibility, result, decision, reviewerId et decidedAt.
Utilisez sourceText pour afficher la source et valueText pour initialiser une modification. Après une décision, affichez settledText : il contient la modification acceptée ou un autre résultat définitif, tandis que valueText conserve la traduction antérieure à la relecture. Tant qu’aucun résultat n’est disponible, settledText est égal à valueText.
quality est le résultat du contrôle qualité pour l’unité : { "findings": [...] }, comme l’explique la référence du pipeline, ou null si le contrôle n’a pas vérifié cette unité. eligibility vaut required, qualityPassed, localeNotCovered ou reused. Seules les unités obligatoires pour lesquelles aucune décision n’a été prise nécessitent une décision humaine. Les autres unités fournissent du contexte. Une valeur définitive non nulle de result peut correspondre à une expiration du délai ou à une solution de repli ; examinez decision pour déterminer si une personne a approuvé ou modifié l’unité.
value est la traduction à l’entrée de l’étape de relecture. Il peut s’agir d’une chaîne ou d’un tableau de segments structurés de texte, de variables et de balisage. Préservez l’identité et l’imbrication des espaces réservés lors des modifications.
Approuver ou modifier #
Approuvez toutes les unités obligatoires restantes sans les modifier :
POST /v2/localization/documents/:documentId/targets/:locale/review/approve-allCette requête n’a pas de corps. Pour soumettre des décisions explicites, envoyez une requête POST à /decisions avec un tableau non vide et des identifiants d’unité uniques :
{
"decisions": [
{ "unitId": "YOUR_FIRST_UNIT_ID", "decision": { "_tag": "Approved" } },
{ "unitId": "YOUR_SECOND_UNIT_ID", "decision": { "_tag": "Edited", "value": "Guardar cambios" } }
]
}Utilisez les identifiants de la demande de relecture récupérée. Pour modifier une valeur structurée, partez de son valueText et envoyez le texte modifié sous la forme Edited.value. Par exemple, Hello {name}<C1>world</C1><C2/> peut devenir Bonjour {name}<C1>tout le monde</C1><C2/>. Conservez les jetons des espaces réservés, leur nombre et l’imbrication du balisage ; les espaces réservés de même niveau peuvent être déplacés. Les délimiteurs littéraux du texte structuré sont échappés sous forme d’entités. L’API analyse ce texte pour le reconvertir en segments structurés. Vous pouvez également soumettre directement un tableau de segments structurés. Les modifications ICU dans une chaîne simple doivent préserver les cas et les nombres adaptés à la langue de la traduction.
En cas de succès, la réponse renvoie la demande de relecture actualisée. Les personnes chargées de la relecture en interne peuvent soumettre un sous-ensemble des unités obligatoires. Les décisions sont définitives. Tant que la cible accepte encore des décisions, une soumission identique par la même personne réutilise la décision enregistrée ; une décision contradictoire est rejetée. L’ensemble soumis est validé avant l’enregistrement de la moindre décision.
LocalizationReviewInvalid (422) signale les soumissions non valides, notamment celles dont les espaces réservés ont été modifiés. LocalizationReviewClosed (409) signifie que la demande de relecture ou une unité ne peut plus accepter cette décision. Une nouvelle tentative après l’achèvement de la cible peut renvoyer 409 même si la première soumission a réussi. Si une réponse est perdue, récupérez la demande de relecture et comparez les décisions enregistrées et les identifiants des personnes chargées de la relecture avant de déterminer ce qu’il reste à faire.
Relecture externe et reprise en main #
Consultez GET /v2/localization/documents/:documentId/targets/:locale/review/vendor-status pour connaître l’état actuel du prestataire externe : unstarted, inProgress, completed ou unknown.
Pour reprendre la main sur une relecture externe, vous devez soumettre en une seule fois des décisions pour toutes les unités obligatoires restantes. Cette soumission clôt la relecture externe et déclenche une tentative d’annulation de la commande auprès du prestataire. Le travail déjà commencé peut toutefois être facturé. Le statut du prestataire peut changer entre la consultation et la soumission ; il ne garantit pas une annulation sans frais.
Attendre le fichier final #
L’échéance de relecture est expiresAt, calculée à partir de readyAt. Les interrogations périodiques et les nouvelles tentatives ne la prolongent pas. À l’expiration du délai, les unités sans décision conservent leurs traductions précédentes, accompagnées d’avertissements ; les décisions acceptées restent en vigueur.
Après la relecture, les étapes suivantes du pipeline peuvent modifier le texte. Récupérez la tâche et téléchargez sa cible terminée pour obtenir le fichier final. Une relecture terminée ne constitue pas, à elle seule, le résultat à télécharger.