Ü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 #

http
POST /v2/organizations/:orgId/localization/jobs
Content-Type: application/json
X-API-Key: YOUR_API_KEY
Idempotency-Key: order-confirmation-v3-de-fr
json
{
  "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 #

FeldErforderlichBedeutung
engineIdJaEngine innerhalb der Organisation, mit der der Aufrufer übersetzen darf.
sourceLocaleJaAusgangssprache.
targetLocalesJaNicht leeres Array von Zielsprachen ohne doppelte Einträge. Die Ausgangssprache eines Dokuments kann nicht zugleich dessen Zielsprache sein.
documentsJaNicht leeres Array von Dokumenten mit eindeutigen key-Werten.
originIdNeinNicht 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:

FeldErforderlichBedeutung
keyJaNicht leerer logischer Dateipfad oder Name, der innerhalb dieses Auftrags eindeutig ist. Behalten Sie ihn über alle Revisionen hinweg unverändert bei.
formatJaFormatobjekt mit einem type und einem formatspezifischen options.
sourceJaSHA-256-Artefaktadresse oder { "content": { ... } } für Inline-JSON.
previousSourceNeinAdresse des vorherigen Quellartefakts. Bei der ersten Übersetzung weglassen oder null verwenden.
previousTranslationsNeinArray von { "locale": "de", "artifact": "SHA256" }. Der Standardwert ist []; jede Sprache darf nur einmal vorkommen und muss zu den Zielsprachen dieses Dokuments gehören.
targetLocalesNeinNicht 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:

http
POST /v2/localization/jobs/:id/start
X-API-Key: YOUR_API_KEY

Die 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.