API für die menschliche Prüfung
Finde ausstehende Dokumentziele, genehmige Übersetzungen und reiche als berechtigter Bewerter Änderungen ein.
Eine Prüfung umfasst ein Dokument in einer Zielsprache. Sie steht zur Verfügung, sobald in der konfigurierten Stufe für die menschliche Prüfung geeignete Einheiten zur Entscheidung bereitstehen. Konfiguriere das Routing für Entscheidungspools, bevor du den Job startest.
Anfragen zur Prüfung erfordern Zugriff auf die Organisation und die Berechtigung zur Prüfung der Übersetzungen der Engine. Entscheidungsanfragen müssen außerdem von einer Person stammen: Authentifiziere dich mit dem Sitzungszugriffstoken oder dem persönlichen API-Schlüssel eines Bewerters. Mit einem Dienstschlüssel der Organisation lassen sich keine menschlichen Entscheidungen einreichen.
Prüfungen finden #
GET /v2/organizations/:orgId/localization/reviews?statuses=open&limit=50Die Antwort ist { "data": [...], "meta": { "nextCursor": "..." } }. Folge den Cursorn, bis nextCursor den Wert null hat.
| Abfragefeld | Werte und Standardwert |
|---|---|
statuses | open, completed, timedOut, cancelled; Standardwert: open. Wiederhole den Parameter, um mehrere Werte anzugeben. |
order | oldest (Standardwert) oder newest. |
limit | 1–100; Standardwert: 50. |
cursor | Opaker Cursor aus der vorherigen Seite. Lass Filter und Sortierung unverändert. |
Um Statuswerte für bereits getroffene Entscheidungen abzurufen, brauchst du die Berechtigung zur Verwaltung der Prüfungen der Organisation. Jede Zusammenfassung enthält documentId, locale, jobId, engineId, engineName, documentKey, sourceLocale, provider, vendorStartedAt, status, readyAt, expiresAt, closedAt, totalUnits und pendingUnits.
Eine Prüfung abrufen #
GET /v2/localization/documents/:documentId/targets/:locale/reviewDie Antwort enthält denselben Ziel- und Engine-Kontext sowie units, Informationen zur Übernahme und einen gegebenenfalls erfassten externen Auftrag. takeover hat den Wert null, bis eine Person die Prüfung übernimmt; externalOrder kann fehlen oder den Wert null haben, wenn kein Auftrag erfasst wurde. Jede Einheit enthält unitId, key, position, source, value, reference, quality, eligibility, result, decision, reviewerId und decidedAt.
Verwende sourceText, um den Ausgangstext anzuzeigen, und valueText als Ausgangspunkt für eine Bearbeitung. Zeige nach einer Entscheidung settledText an: Dieser Wert enthält die akzeptierte Änderung oder ein anderes endgültiges Ergebnis, während valueText die Übersetzung vor der Prüfung beibehält. Bis ein Ergebnis verfügbar ist, entspricht settledText dem Wert von valueText.
quality ist die Ausgabe der Qualitätsschranke für die Einheit: { "findings": [...] }, wie in der Pipeline-Referenz beschrieben, oder null, wenn die Schranke die Einheit nicht kontrolliert hat. eligibility hat den Wert required, qualityPassed, localeNotCovered oder reused. Nur erforderliche Einheiten, für die noch keine Entscheidung vorliegt, benötigen eine menschliche Entscheidung. Andere Einheiten liefern Kontext. Ein endgültiger Wert von result, der nicht null ist, kann auf eine Zeitüberschreitung oder einen Fallback zurückgehen; sieh dir decision an, um festzustellen, ob eine Person die Einheit genehmigt oder bearbeitet hat.
value ist die Übersetzung am Übergang zur Prüfung. Sie kann eine Zeichenfolge oder ein Array aus strukturierten Text-, Variablen- und Markup-Segmenten sein. Behalte beim Bearbeiten die Identitäten und die Verschachtelung der Platzhalter bei.
Genehmigen oder bearbeiten #
Genehmige alle verbleibenden erforderlichen Einheiten ohne Änderungen:
POST /v2/localization/documents/:documentId/targets/:locale/review/approve-allDiese Anfrage hat keinen Anfragekörper. Um explizite Entscheidungen zu treffen, sende eine POST-Anfrage an /decisions mit einem nicht leeren Array und eindeutigen Einheiten-IDs:
{
"decisions": [
{ "unitId": "YOUR_FIRST_UNIT_ID", "decision": { "_tag": "Approved" } },
{ "unitId": "YOUR_SECOND_UNIT_ID", "decision": { "_tag": "Edited", "value": "Guardar cambios" } }
]
}Verwende die IDs aus der abgerufenen Prüfung. Um einen strukturierten Wert zu bearbeiten, nutze dessen valueText als Ausgangspunkt und sende den bearbeiteten Text als Edited.value. Beispielsweise kann Hello {name}<C1>world</C1><C2/> zu Bonjour {name}<C1>tout le monde</C1><C2/> werden. Behalte die Platzhalter-Tokens, ihre Anzahl und die Markup-Verschachtelung bei; Platzhalter auf derselben Ebene dürfen verschoben werden. Literale Trennzeichen in strukturiertem Text werden als Entitäten maskiert. Die API wandelt diesen Text wieder in strukturierte Segmente um. Du kannst auch direkt ein Array strukturierter Segmente einreichen. Bei ICU-Änderungen in einfachen Zeichenfolgen müssen die sprachspezifischen Fälle und Anzahlen der Übersetzung erhalten bleiben.
Bei Erfolg enthält die Antwort die aktualisierte Prüfung. Interne Bewerter können eine Teilmenge der erforderlichen Einheiten einreichen. Entscheidungen sind endgültig. Solange das Ziel noch Entscheidungen annimmt, wird bei einer identischen Einreichung durch denselben Bewerter die gespeicherte Entscheidung wiederverwendet; eine widersprüchliche Entscheidung wird abgelehnt. Die gesamte Einreichung wird validiert, bevor eine der darin enthaltenen Entscheidungen gespeichert wird.
LocalizationReviewInvalid (422) kennzeichnet ungültige Einreichungen, darunter solche mit geänderten Platzhaltern. LocalizationReviewClosed (409) bedeutet, dass die Prüfung oder eine Einheit diese Entscheidung nicht mehr annehmen kann. Ein erneuter Versuch nach Abschluss des Ziels kann 409 zurückgeben, selbst wenn die erste Einreichung erfolgreich war. Wenn eine Antwort verloren geht, rufe die Prüfung ab und vergleiche die gespeicherten Entscheidungen und Bewerter-IDs, bevor du entscheidest, was noch zu tun ist.
Externe Prüfung und Übernahme #
Lies den aktuellen Status des externen Anbieters aus GET /v2/localization/documents/:documentId/targets/:locale/review/vendor-status aus: unstarted, inProgress, completed oder unknown.
Um eine externe Prüfung zu übernehmen, musst du Entscheidungen für alle verbleibenden erforderlichen Einheiten in einer einzigen Einreichung übermitteln. Dadurch wird die externe Prüfung geschlossen und die Stornierung des Auftrags beim Anbieter versucht. Bereits begonnene Arbeiten können dennoch in Rechnung gestellt werden. Der Anbieterstatus kann sich zwischen dem Abrufen und dem Einreichen ändern; er garantiert keine kostenlose Stornierung.
Auf die endgültige Datei warten #
Die Frist für die Prüfung ist expiresAt und wird aus readyAt berechnet. Regelmäßige Abfragen und erneute Versuche verlängern sie nicht. Bei einer Zeitüberschreitung behalten Einheiten ohne Entscheidung ihre vorherigen Übersetzungen bei und erhalten Warnungen; akzeptierte Entscheidungen bleiben bestehen.
Nach der Prüfung können spätere Pipeline-Stufen den Text noch ändern. Rufe den Job ab und lade dessen abgeschlossenes Ziel herunter, um die endgültige Datei zu erhalten. Eine abgeschlossene Prüfung ist für sich genommen noch nicht das Download-Ergebnis.