String-Kataloge über die API lokalisieren

Das Key-basierte Format von Transept ist .tstrings.json: eine Liste von Units, jeweils mit einer stabilen id, einer source und optional einem context (was der String ist, wo er erscheint), einer max_length sowie placeholders. Die ID ist die verbindliche Referenz: Über sie behalten Übersetzungen bei Re-Importen ihre Identität, der Review-Status bleibt erhalten und der Export ordnet jeder Sprache den passenden Key zu. Beide Zusatzfelder haben einen konkreten Nutzen: Der Kontext dient dem Modell als Orientierungshilfe, und ein Zeichenlimit wird durch automatisches Kürzen mit anschließendem Neuversuch erzwungen.

CSV-, gettext-PO- und XLIFF-Dateien werden über die App oder den Upload-Endpunkt als dieselben Key-basierten Units importiert; unter Strings-Dateien erfahren Sie, wie die einzelnen Formate zugeordnet werden. In diesem Artikel geht es darum, den Workflow programmatisch zu steuern, wobei .tstrings.json das native Format ist.

POST /documents/import-strings mit dem Katalog als JSON. Die Zielsprachen werden in einer festen Reihenfolge aufgelöst: Explizit im Request angegebene target_language / target_languages haben Vorrang, ansonsten werden die target_locales aus dem Katalog-Header verwendet. Fehlen beide, schlägt der Aufruf sofort mit no_target_languages fehl, anstatt ein Dokument ohne Zielsprachen zu importieren. Der Aufruf gibt eine processing_job_id zurück; rufen Sie GET /document-jobs/{id} per Polling ab, bis der Import abgeschlossen ist und Sie die Dokument-IDs erhalten.

Bereits in der Datei enthaltene Übersetzungen (targets: {de: "…"}) werden direkt als aktive Übersetzung für den jeweiligen String übernommen – kostenlos und ohne dass ein Übersetzungslauf nötig ist. Sie fließen sofort in Ihr Translation Memory ein; dies entspricht dem Verhalten beim Import bestehender Übersetzungen über die App.

# BASE="https://app.transept.ai/api/public/v1"; KEY from Settings → Developer
curl -s -X POST $BASE/documents/import-strings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document": {
        "format": "transept-strings", "version": 1, "source_locale": "en",
        "target_locales": ["de", "fr", "uk"],
        "metadata": {"name": "App UI"},
        "units": [
          {"id": "app.save", "source": "Save", "context": "Toolbar button"},
          {"id": "app.greeting", "source": "Welcome, {name}", "context": "Dashboard header"}
        ]}}'
# → { processing_job_id }; poll GET /document-jobs/{id}

Senden Sie den gesamten aktuellen Katalog an POST /documents/{id}/import-strings, keine gekürzte Version. Der Server führt einen Abgleich anhand der Unit-ID durch und meldet zurück, was er gefunden hat (added, changed, unchanged, removed), zusammen mit den delta_block_ids: den exakten Blöcken pro Sprachversion, die bearbeitet werden müssen. Übergeben Sie dieses Objekt unverändert als block_ids für einen Sammellauf, damit nur diese Blöcke übersetzt werden. Sie können beim Re-Import auch run direkt mitgeben, um die Übersetzung des Deltas im selben Aufruf anzustoßen.

Unveränderte Units behalten ihre Übersetzungen und ihren Review-Status; dies ist die API-Entsprechung zu Nur Geändertes übersetzen. Wenn Sie einen einzelnen String in einem Katalog mit Hunderten von Einträgen korrigieren, kostet das auch nur einen String.

# 1. Re-submit the whole current catalog; the server diffs it by unit id
curl -s -X POST $BASE/documents/<master>/import-strings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d @app-ui.tstrings.json
# → { units: {added, changed, unchanged, removed}, delta_block_ids: {<doc_id>: [block ids]} }

# 2. Feed delta_block_ids VERBATIM into a group run; only those blocks translate
curl -s -X POST $BASE/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document_id": "<master>", "template_id": "end_to_end",
       "target_languages": "all", "block_ids": { "<doc_id>": ["<block id>", "…"] }}'

GET /documents/{id}/content?format=strings beim Hauptdokument gibt eine einzelne .tstrings.json mit den Übersetzungen aller Sprachen zurück, zugeordnet über die Unit-ID: ein Aufruf, bereit für den Commit oder die Einbindung in Ihren Build. Derselbe Endpunkt liefert auch sprachspezifische Versionen (markdown, html, csv, xliff, tmx), falls eine Pipeline stattdessen ein bestimmtes Austauschformat benötigt; die vollständige Tabelle finden Sie unter Transept mit der API automatisieren.

Bei Katalogen, die als CSV, PO oder XLIFF importiert wurden, füllt der Export der Originaldatei stattdessen die Zellen und Einträge Ihrer eigenen Datei aus (Byte für Byte identisch mit Ihrem Upload, ergänzt um die Übersetzungen), sodass die Datei direkt wieder in das System geladen werden kann, aus dem sie stammt.

curl -s "$BASE/documents/<master>/content?format=strings" \
  -H "Authorization: Bearer $KEY"
# → one .tstrings.json with every language keyed by unit id