API pro lidskou kontrolu

Vyhledejte cílové dokumenty čekající na kontrolu, schvalujte překlady a odesílejte úpravy jako oprávněný kontrolor.

Kontrola se vztahuje na jeden dokument v jednom cílovém jazyce. Zpřístupní se, jakmile jsou v nastavené fázi lidské kontroly připraveny jednotky splňující podmínky pro rozhodnutí. Před spuštěním úlohy nastavte směrování do rozhodovacích skupin.

Požadavky týkající se kontroly vyžadují přístup k organizaci a oprávnění kontrolovat překlady engine. Požadavky na rozhodnutí navíc vyžadují ověření konkrétní osoby: použijte přístupový token relace kontrolora nebo jeho osobní klíč API. Služebním klíčem organizace nelze odesílat lidská rozhodnutí.

Vyhledání kontrol #

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

Odpověď má podobu { "data": [...], "meta": { "nextCursor": "..." } }. Procházejte další stránky pomocí kurzorů, dokud nextCursor nebude mít hodnotu null.

Pole dotazuHodnoty a výchozí hodnota
statusesopen, completed, timedOut, cancelled; výchozí hodnota je open. Chcete-li zadat více hodnot, parametr zopakujte.
orderoldest (výchozí) nebo newest.
limit1–100; výchozí hodnota je 50.
cursorNeprůhledný kurzor z předchozí stránky. Filtry a pořadí řazení ponechte beze změny.

Dotazy na stavy, ve kterých už bylo rozhodnuto, vyžadují oprávnění spravovat kontroly organizace. Každý souhrn uvádí documentId, locale, jobId, engineId, engineName, documentKey, sourceLocale, provider, vendorStartedAt, status, readyAt, expiresAt, closedAt, totalUnits a pendingUnits.

Načtení jedné kontroly #

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

Odpověď obsahuje stejný kontext cíle a engine a navíc units, informace o převzetí a případnou zaznamenanou externí objednávku. takeover má hodnotu null, dokud kontrolu nepřevezme člověk; pokud nebyla zaznamenána žádná objednávka, externalOrder může chybět nebo mít hodnotu null. Každá jednotka obsahuje unitId, key, position, source, value, reference, quality, eligibility, result, decision, reviewerId a decidedAt.

Pomocí sourceText zobrazte zdrojový text a pomocí valueText inicializujte úpravu. Po rozhodnutí zobrazte settledText: obsahuje přijatou úpravu nebo jiný konečný výsledek, zatímco valueText uchovává překlad z doby před kontrolou. Dokud není výsledek k dispozici, settledText se rovná valueText.

quality je výstupem brány kvality pro danou jednotku: { "findings": [...] }, jak popisuje reference pipeline, nebo null, pokud brána jednotku nezkontrolovala. eligibility má hodnotu required, qualityPassed, localeNotCovered nebo reused. Rozhodnutí člověka vyžadují pouze povinné jednotky, o kterých ještě nebylo rozhodnuto. Ostatní jednotky poskytují kontext. Konečná hodnota result odlišná od null může být výsledkem vypršení časového limitu nebo použití náhradního řešení; podle decision zjistíte, zda jednotku schválil nebo upravil člověk.

value je překlad v okamžiku předání ke kontrole. Může jít o řetězec nebo pole strukturovaných segmentů textu, proměnných a značek. Při úpravách zachovejte identitu zástupných symbolů a jejich vnoření.

Schválení nebo úprava #

Schvalte všechny zbývající povinné jednotky beze změn:

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

Tento požadavek nemá tělo. Chcete-li odeslat explicitní rozhodnutí, odešlete požadavek POST na /decisions s neprázdným polem a jedinečnými ID jednotek:

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

Použijte ID z načtené kontroly. Při úpravě strukturované hodnoty vyjděte z jejího valueText a upravený text odešlete jako Edited.value. Například Hello {name}<C1>world</C1><C2/> lze změnit na Bonjour {name}<C1>tout le monde</C1><C2/>. Zachovejte tokeny zástupných symbolů, jejich počty a vnoření značek; zástupné symboly na stejné úrovni lze přesouvat. Doslovné oddělovače ve strukturovaném textu jsou escapovány pomocí entit. API tento text převede zpět na strukturované segmenty. Pole strukturovaných segmentů můžete odeslat i přímo. Při úpravách ICU v prostém řetězci je nutné zachovat lokalizované varianty a počty v překladu.

Úspěšná odpověď vrátí aktualizovanou kontrolu. Interní kontroloři mohou odeslat rozhodnutí jen pro část povinných jednotek. Rozhodnutí jsou konečná. Dokud cíl přijímá rozhodnutí, při totožném odeslání od stejného kontrolora se znovu použije uložené rozhodnutí; konfliktní rozhodnutí bude odmítnuto. Před uložením kteréhokoli rozhodnutí se ověří celá odeslaná sada.

LocalizationReviewInvalid (422) označuje neplatné odeslané údaje, včetně změněných zástupných symbolů. LocalizationReviewClosed (409) znamená, že kontrola nebo jednotka už dané rozhodnutí nemůže přijmout. Opakovaný pokus po dokončení cíle může vrátit 409, i když první odeslání proběhlo úspěšně. Pokud se odpověď ztratí, načtěte kontrolu a porovnejte uložená rozhodnutí a ID kontrolorů. Teprve pak určete, co ještě zbývá udělat.

Externí kontrola a převzetí #

Aktuální stav u externího poskytovatele zjistíte z GET /v2/localization/documents/:documentId/targets/:locale/review/vendor-status: unstarted, inProgress, completed nebo unknown.

Při převzetí externí kontroly je nutné v jediném požadavku odeslat rozhodnutí pro všechny zbývající povinné jednotky. Tím se externí kontrola uzavře a systém se pokusí zrušit objednávku u poskytovatele. Již zahájená práce může být přesto zpoplatněna. Stav u poskytovatele se mezi načtením a odesláním může změnit a nezaručuje bezplatné zrušení.

Čekání na finální soubor #

Lhůta pro kontrolu končí v expiresAt a vypočítává se z readyAt. Pravidelné dotazování ani opakované pokusy ji neprodlužují. Po vypršení časového limitu si jednotky bez rozhodnutí ponechají předchozí překlady s varováními; přijatá rozhodnutí zůstávají v platnosti.

Po kontrole mohou další fáze pipeline text změnit. Chcete-li získat finální soubor, načtěte úlohu a stáhněte její dokončený cíl. Samotná dokončená kontrola není výsledkem ke stažení.