Dokumente übersetzen
Lade Quelldateien und frühere Übersetzungen hoch, starte einen Lokalisierungsauftrag und lade die fertigen Dateien herunter.
Mit Dokumentaufträgen übersetzt du Dateien, ohne ihr Format zu verändern. Ein Auftrag kann mehrere Dateien und Zielsprachen enthalten. Die API adressiert jede Datei über den SHA-256-Hash ihrer exakten Bytes.
Du benötigst einen API-Schlüssel, eine Organisations-ID und eine Engine-ID. In der Anleitung zur Dateilokalisierung findest du ein vollständiges Node.js-Beispiel.
Format auswählen #
Lege format.type für jedes Dokument fest:
| Format | Typ |
|---|---|
| JSON / JSONC | json / jsonc |
| Markdown / MDX / Markdoc | md / mdx / markdoc |
| HTML | html |
| TypeScript / PHP | typescript / php |
| YAML / YAML mit Sprache als Wurzelschlüssel / OpenAPI YAML | yaml / yaml-root-key / yaml-openapi |
| Android / Flutter ARB | android / flutter |
| Apple-Zeichenfolgen / Pluralwörterbücher / Zeichenfolgenkataloge | xcode-strings / xcode-stringsdict / xcode-xcstrings |
| Gettext / XLIFF / SubRip | po / xliff / srt |
| Reiner Text | txt |
| CSV-Tabelle mit einer Spalte pro Sprache | csv |
| Java-Properties | properties |
| Payload-Inhalte | payload |
Die Formatreferenzen erläutern die Dateistrukturen und Steuerungsmöglichkeiten. Die API format.options verwendet den Schnittstellenvertrag für Dokumente; die CLI-Konfiguration bildet ihre eigenen Optionsnamen auf diesen Vertrag ab. Beispielsweise verwendet die API frontmatterFields für Markdown und componentProps für Komponenteneigenschaften. Selektoren für JSON-Schlüssel verwenden JSONPath.
Formatoptionen festlegen #
Lass format.options weg, um die Standardwerte zu verwenden. Lege nur Optionen fest, die der ausgewählte Typ unterstützt:
| Typ | Optionen |
|---|---|
json, jsonc | JSON-Optionen: Schlüsselregeln, Geltungsbereiche, Kontext, Hinweise und Einfügen der Sprache. |
typescript, php, yaml, yaml-root-key | lockedKeys, preservedKeys, ignoredKeys (Standard: []); optional keyScope und termScope, jeweils nicht leer. |
md | frontmatterFields (Standard: ["$.title", "$.description"]); optional termScope, nicht leer. |
mdx, markdoc | Markdown-Optionen sowie componentProps (Standard: []). |
html | componentProps (Standard: []), zusätzlich zu den im Handler integrierten übersetzbaren Attributen. |
xcode-stringsdict | lockedKeys und preservedKeys (Standard: []); optional termScope, nicht leer. |
flutter, xcode-strings, xcode-xcstrings, android, yaml-openapi | Optional termScope, nicht leer. |
csv | Optional keyColumn, die Überschrift der Schlüsselspalte (Standard: die erste Zelle der Kopfzeile). |
properties | lockedKeys, preservedKeys, ignoredKeys (Standard: []) und optional ein nicht leeres keyScope, die als Muster im bisherigen Format mit dem gesamten Schlüssel abgeglichen werden oder als JSONPath, wenn ein Muster mit $ beginnt; optional ein nicht leeres termScope; lockedPatterns (Standard: []), reguläre RE2-Ausdrücke, die in Werten unübersetzt bleiben. |
payload, po, xliff, srt, txt | Keine zusätzlichen Optionen. |
Schlüsselregeln, Geltungsbereiche für Schlüssel und Frontmatter-Felder verwenden JSONPath-Abfragen. termScope wählt vollständige Quelleinheiten aus, die mindestens einen der angegebenen Begriffe als Teilzeichenfolge enthalten. Dabei wird die Groß- und Kleinschreibung berücksichtigt; "cat" kann mit "catalog" übereinstimmen. Unterstützt ein Format sowohl keyScope als auch termScope, wird bei Angabe beider die Schnittmenge ausgewählt. Beide Geltungsbereiche setzen vorhandene Übersetzungen voraus, in die die Ergebnisse eingefügt werden. Auswahl und Wiederverwendung hängen vom Format ab, wie unter inkrementelle Aktualisierungen beschrieben. Diese API-Optionen unterscheiden sich von der Formatunterstützung der CLI für --key.
Eine Regel für Komponenteneigenschaften enthält props, ein nicht leeres Array mit Eigenschaftsnamen, sowie optional components, ein nicht leeres Array, das die Regel auf die darin genannten Komponenten beschränkt. Lässt du components weg, gilt die Regel für jede Komponente. Für MDX:
{
"type": "mdx",
"options": {
"frontmatterFields": ["$.title", "$.description", "$.sidebar.label"],
"componentProps": [{ "components": ["Callout"], "props": ["title"] }]
}
}Damit werden die ausgewählten Frontmatter-Felder und die als Literale angegebenen Callout-Titel zusammen mit dem Fließtext des Dokuments übersetzt. Informationen zu geschütztem Code, Ausdrücken und dem Verhalten bei der Rekonstruktion findest du in der Formatreferenz.
Auftrag mit Artefaktadressen erstellen #
Berechne den Hash genau der Bytes, die du hochladen möchtest. In Node.js:
import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";
const bytes = await readFile("messages/en.json");
const address = createHash("sha256").update(bytes).digest("hex");Erstelle einen Auftrag und verwende die daraus resultierende Adresse als source des Dokuments:
{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de"],
"documents": [
{
"key": "messages/en.json",
"format": { "type": "json" },
"source": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
]
}Ersetze die Beispieladresse durch den berechneten Hash. Speichere die zurückgegebene Auftrags-ID. uploads listet die Eingabeartefakte auf, die noch nicht gespeichert sind; bereits gespeicherte Inhalte musst du nicht erneut hochladen.
Bytes hochladen und Auftrag starten #
Sende für jeden uploads-Eintrag einen authentifizierten PUT an dessen uploadUrl, mit Content-Type: application/octet-stream und den ursprünglichen Bytes als Anfrageinhalt. Lade die Quelldateien und alle referenzierten früheren Dateien hoch, bevor du den Auftrag startest.
Für jedes Artefakt gilt eine Größenbegrenzung von 25 MiB. Bei einer Hash-Abweichung wird ArtifactChecksumMismatch zurückgegeben, bei einer zu großen Datei RequestBodyTooLarge. Wenn du den Hash eines Textes berechnest und danach vor dem Hochladen dessen Zeilenenden änderst, verändern sich die Bytes und die Verifizierung schlägt fehl.
Rufe POST /v2/localization/jobs/:id/start auf, sobald alle Uploads erfolgreich abgeschlossen sind. Artefakt-Uploads werden nur vor dem Start des Auftrags akzeptiert. Rufe den Fortschritt des Auftrags für die Zielsprachen ab und lade anschließend die fertigen Dateien über die zurückgegebenen URLs herunter.
Vorhandenes Dokument aktualisieren #
Halte für eine inkrementelle Aktualisierung drei Eingaben bereit: die neue Quelldatei, die vorherige Quelldatei und die aktuelle Übersetzung für jede Zielsprache. Gib Folgendes an:
source: die Artefaktadresse der neuen Quelldatei.previousSource: die Quelladresse, die für die vorherige Revision verwendet wurde.previousTranslations: ein{ "locale": "de", "artifact": "..." }-Eintrag pro verfügbarer Übersetzung.
Stelle sicher, dass lokale manuelle Änderungen in den bereitgestellten Bytes der vorherigen Zieldatei enthalten sind. Der Format-Handler kann unveränderte Inhalte wiederverwenden und geänderte Inhalte übersetzen. Bei gewöhnlichem JSON entfällt die Wiederverwendung unveränderter Quellinhalte, wenn du die vorherige Quelldatei weglässt. Andere Formate können vorhandene Zielinhalte nach ihren eigenen Zusammenführungsregeln übernehmen. Bewahre den vollständigen Ausgangsstand auf, wenn du eine Änderung an der Quelle von einer unveränderten Nachricht unterscheiden musst.
Eine über keyScope oder termScope eingegrenzte Anfrage erfordert eine vorherige Übersetzung für jede Zielsprache. JSON, JSONC, TypeScript und PHP generieren die ausgewählten Zeichenfolgen neu, auch bei unveränderten Quellwerten, und führen sie mit der vorhandenen Zieldatei zusammen. YAML, YAML mit Sprache als Wurzelschlüssel und OpenAPI YAML können unveränderte ausgewählte Inhalte wiederverwenden, wenn eine vorherige Quelldatei bereitgestellt wird. XCStrings kann eingebettete oder bereitgestellte Zielwerte auch ohne vorherige Quelldatei wiederverwenden. Eine ausgewählte Einheit führt daher nicht immer zu neuer Übersetzungsarbeit.
Gib der Engine die gewünschte Terminologie oder Regel vor, bevor du eine Neugenerierung anforderst, und sieh dir anschließend das Ergebnis in der Zieldatei an. Wenn du eine Formulierung exakt korrigieren möchtest, bearbeite die Zieldatei direkt. So bist du nicht darauf angewiesen, dass die Neugenerierung eine bestimmte Formulierung erzeugt.
Speichere einen Ausgangsstand, bevor du einen späteren Auftrag erstellst. Verwende dafür PUT /v2/organizations/:orgId/localization/artifacts/:address mit Authentifizierung und den Dateibytes als Anfrageinhalt. Diese Route erfordert Übersetzungszugriff auf eine Engine in der Organisation und gibt Artefaktmetadaten zurück. Es gelten dieselbe Größenbegrenzung von 25 MiB und dieselben Hash-Prüfungen.
Lade die Ergebnisse zunächst in temporäre Dateien herunter. Vergleiche sie sowohl mit der eingereichten Quellrevision als auch mit allen Änderungen an den Zieldateien seit der Einreichung, bevor du Anwendungsdateien ersetzt. Übersetzungen nach der Prüfung beibehalten erläutert den entsprechenden CLI-Workflow.