Übersetzungsaufträge
Aufträge mit einem oder mehreren Dokumenten und Zielsprachen erstellen und starten.
Ein Auftrag übersetzt Dokumente über eine Lokalisierungs-Engine. Jedes Dokument hat einen festen Schlüssel und ein Ziel pro angeforderter Sprache. Verwenden Sie Inline-JSON für Inhalte im Arbeitsspeicher oder Artefaktadressen für Dateien.
Alle folgenden Routen verwenden https://api.lingo.dev und API-Authentifizierung.
Auftrag erstellen #
POST /v2/organizations/:orgId/localization/jobs
Content-Type: application/json
X-API-Key: YOUR_API_KEY
Idempotency-Key: order-confirmation-v3-de-fr{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"documents": [
{
"key": "order-confirmation.json",
"format": { "type": "json" },
"source": { "content": { "subject": "Your order is confirmed" } }
}
]
}Anfragefelder #
| Feld | Erforderlich | Bedeutung |
|---|---|---|
engineId | Ja | Engine innerhalb der Organisation, mit der der Aufrufer übersetzen darf. |
sourceLocale | Ja | Ausgangssprache. |
targetLocales | Ja | Nicht leeres Array von Zielsprachen ohne doppelte Einträge. Die Ausgangssprache eines Dokuments kann nicht zugleich dessen Zielsprache sein. |
documents | Ja | Nicht leeres Array von Dokumenten mit eindeutigen key-Werten. |
originId | Nein | Nicht leere Kennung mit bis zu 512 Zeichen für den Speicherort der Dokumente, zum Beispiel github:acme/web. Sie verknüpft spätere Änderungen aus dieser Quelle mit der Übersetzungsmessung. |
Jedes Dokument enthält:
| Feld | Erforderlich | Bedeutung |
|---|---|---|
key | Ja | Nicht leerer logischer Dateipfad oder Name, der innerhalb dieses Auftrags eindeutig ist. Behalten Sie ihn über alle Revisionen hinweg unverändert bei. |
format | Ja | Formatobjekt mit einem type und einem formatspezifischen options. |
source | Ja | SHA-256-Artefaktadresse oder { "content": { ... } } für Inline-JSON. |
previousSource | Nein | Adresse des vorherigen Quellartefakts. Bei der ersten Übersetzung weglassen oder null verwenden. |
previousTranslations | Nein | Array von { "locale": "de", "artifact": "SHA256" }. Der Standardwert ist []; jede Sprache darf nur einmal vorkommen und muss zu den Zielsprachen dieses Dokuments gehören. |
targetLocales | Nein | Nicht leere, abweichende Auswahl von Zielsprachen für dieses Dokument, ohne doppelte Einträge. Wenn das Feld fehlt oder null enthält, werden die Zielsprachen des Auftrags verwendet. |
Wenn Sie keyScope oder termScope verwenden, geben Sie für jedes Ziel eine vorherige Übersetzung an. Siehe Dokumentformate und Aktualisierungen.
Idempotenz #
Senden Sie einen nicht leeren Idempotency-Key mit höchstens 255 Zeichen. Schlüssel gelten jeweils innerhalb einer Engine; das Präfix content-sync: ist reserviert. Bewahren Sie den Schlüssel zusammen mit der ursprünglichen Anfrage auf. Wenn die Antwort auf die Erstellungsanfrage unklar ist, wiederholen Sie die Anfrage unverändert.
Wenn Sie einen Schlüssel erneut verwenden, wird der ursprünglich damit erstellte Auftrag zurückgegeben. Die Dokumente oder Sprachen dieses Auftrags werden dadurch nicht aktualisiert. Verwenden Sie für geänderte Aufgaben einen neuen Schlüssel. Eine widersprüchliche Ausführungsoption kann zu LocalizationJobIdempotencyKeyReused (422) führen.
Antwort auf die Erstellungsanfrage #
Bei erfolgreicher Erstellung werden HTTP 200 und die Auftragsantwort zurückgegeben, normalerweise mit status: { "_tag": "Pending" }. Speichern Sie id dauerhaft, bevor Sie fortfahren. Das Array uploads listet fehlende Eingabeartefakte als { "address": "...", "uploadUrl": "..." } auf.
Bei der Erstellung werden Inline-Quellen gespeichert. Die Übersetzung wird dabei nicht gestartet, auch wenn uploads leer ist.
Hochladen und starten #
Laden Sie jedes fehlende Artefakt an die zugehörige uploadUrl hoch. Verwenden Sie dafür einen authentifizierten PUT mit den ursprünglichen Bytes. Rufen Sie anschließend Folgendes auf:
POST /v2/localization/jobs/:id/start
X-API-Key: YOUR_API_KEYDie Startanfrage hat keinen Body. Die Antwort mit HTTP 200 enthält den aktuellen Auftragsdatensatz. Sie können den Start desselben Auftrags gefahrlos wiederholen, wenn unklar ist, ob er zur Ausführung übergeben wurde. Dabei wird weder ein weiterer Auftrag erstellt noch ein abgeschlossener Auftrag erneut ausgeführt.
Beim Start werden die hochgeladenen Artefakte, die Engine-Konfiguration und die Kontolimits validiert. ArtifactsNotUploaded (409) listet fehlende Eingaben auf. Bei Erreichen des täglichen Token-Limits (429) oder unzureichendem Guthaben bleibt der Auftrag ausstehend. Beheben Sie die Ursache, bevor Sie ihn erneut starten. Siehe Fehler.
Pipeline-Stufen konfigurieren #
Konfigurieren Sie die Pipeline der Engine vor dem Start. Ihre Konfiguration wird beim Start erfasst. Die daraus resultierenden Stufen für die Ziele des Auftrags zeigen, welche Aufgaben tatsächlich ausgewählt wurden, nachdem die Verfügbarkeit im jeweiligen Tarif berücksichtigt wurde.
Ergebnisse abrufen und Fehler beheben #
Rufen Sie den Auftrag ab, um jedes Ziel anzusehen und fertige Dateien herunterzuladen. Anhand des Stufenfortschritts können Sie zwischen Modellverarbeitung, Wartezeiten auf eine Prüfung, übersprungenen Aufgaben und Fehlern unterscheiden.
Ein fehlgeschlagener Auftrag kann dennoch abgeschlossene Ziele enthalten. Behalten Sie diese Ergebnisse. Beheben Sie zunächst die Ursache und reichen Sie dann nur die Aufgaben, die erneut generiert werden müssen, mit einem neuen Idempotenzschlüssel ein. Bewahren Sie Quellrevisionen zusammen mit den Auftrags-IDs auf, damit eine spätere Auslieferung keine neueren Übersetzungen überschreibt.
Listen Sie Aufträge auf, um Einreichungen nach Engine, Status, Auslöser oder Dienstschlüssel zu finden.