Lokalisierung per API: Strings, E-Mails und Dokumente – End-to-End

Alles, was der Editor kann, lässt sich auch per Skript erledigen: Import, Übersetzung in verschiedene Sprachen mit Ihrem Glossar und Translation Memory, Review und Export. Dieser Guide führt Sie vom Key zum übersetzten Output und anschließend durch die einzelnen Phasen des Workflows. Die interaktive Referenz und das OpenAPI-JSON bilden die vollständige Spezifikation; transept.ai/developers ist die One-Page-Version dieses Guides. Eine kleine Besonderheit bei der Benennung vor dem ersten Aufruf: Die Abrechnungseinheit wird für Nutzer überall als Wörter ausgewiesen, in den Feldern der API-Antworten bleibt jedoch die historische Bezeichnung credits (estimatedCredits, spendable) erhalten. Die Menge ist identisch.

Key abrufen

Einstellungen → Developer in der App; kopieren Sie das Secret einmalig. Bei Anfragen wird es als Authorization: Bearer tsk_live_… übermittelt – ausschließlich im Header, niemals in der URL.

Keys sind über Scopes definiert: Entweder besteht Vollzugriff oder es gibt Lese-/Schreibrechte für einzelne Bereiche (Dokumente, Runs, Glossare, Styleguides, Translation Memory, Webhooks, Projekte). Ein Aufruf außerhalb dieser Scopes liefert einen 403 zurück, der die fehlende Berechtigung benennt. Ein Key kann niemals weitere Keys erstellen; die Key-Verwaltung erfolgt ausschließlich in der App.

Der Workflow in fünf Aufrufen

Key-Funktion verifizieren, Dokument erstellen, Kosten für den Run schätzen, starten und das Ergebnis abrufen.

export KEY="tsk_live_…"
BASE="https://app.transept.ai/api/public/v1"

# 1: who am I, what can this key do, what's the balance?
curl -s $BASE/me -H "Authorization: Bearer $KEY"

# 2: a document plus its target-language fan-out, in one call
curl -s -X POST $BASE/documents \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Welcome email", "content": "# Welcome\n\nStart your free trial.",
       "content_type": "markdown", "source_language": "en",
       "target_language": "de", "target_languages": ["fr", "uk"]}'
# → { document_id, language_group: [ {id, target_language}, … ] }

# 3: price it (free, no side effects), then run it across every language
curl -s $BASE/workflow-templates -H "Authorization: Bearer $KEY"   # discover ids

curl -s -X POST $BASE/group-runs/estimate \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'
# → { lanes: [ {language, estimatedCredits, minCredits} ], totals: {sufficient} }

curl -s -X POST $BASE/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-2026-08-05" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'
# → { id: <group_run_id>, runs: [ {job_id, language, block_count} ] }

# 4: wait by polling, or get pushed a signed event instead
curl -s $BASE/group-runs/<group_run_id> -H "Authorization: Bearer $KEY"
# → { status, runs: [ {language, status, progress, gate} ] }

# 5: read the results in the format your pipeline wants
curl -s "$BASE/documents/<version-id>/content?format=markdown" \
  -H "Authorization: Bearer $KEY"

Drei Tipps für den Start: zuerst schätzen (kostenlos; die Spanne reicht vom Mindest- bis zum Höchstbetrag, wobei der Höchstbetrag am Ende auf die tatsächlichen Kosten korrigiert wird), **senden Sie einen ****Idempotency-Key** bei Job-erstellenden POST-Anfragen (ein Retry liefert das erste Ergebnis zurück, anstatt doppelt abzurechnen) und registrieren Sie einen Webhook (POST /webhooks {url, events: ["group_run.completed"]}), anstatt Polling zu verwenden. Die Zustellungen sind HMAC-signiert und verfügen über automatische Wiederholungsversuche sowie ein Zustellungsprotokoll.

Drei Arten von Input

Fließtext und E-Mails

POST /documents mit content_type: "html" bewahrt Formatierungen, Links und Template-Platzhalter während der Übersetzung; format=html liefert die übersetzte E-Mail in der ursprünglichen Form zurück. Oder überspringen Sie den Request: Setzen Sie einen Workflow-Trigger auf „Der Request-Body ist der Inhalt“ und richten Sie Ihren ESP, Zapier/n8n oder Ihre CI auf die Trigger-URL aus:

# the trigger URL (with its secret) comes from the workflow's trigger card;
# the secret IS the auth, so no Authorization header
curl -s -X POST $BASE/hooks/<trigger-secret> \
  -H "Content-Type: application/json" \
  -d '{"content": "<h1>Welcome!</h1><p>Your trial starts today.</p>",
       "content_type": "html",
       "title": "Trial welcome",
       "external_id": "welcome-v4"}'
# → 202 { run id, document_id, created }

# raw bodies work too: POST the markdown/HTML itself with its Content-Type
curl -s -X POST $BASE/hooks/<trigger-secret> \
  -H "Content-Type: text/markdown" \
  --data-binary $'# Welcome\n\nStart your free trial.'

Der Trigger legt fest, ob jede Zustellung ein neues Dokument erstellt oder ein einzelnes, festes Dokument aktualisiert (bei einem Update wird der Inhalt neu abgeglichen, sodass nur geänderte Blöcke neu übersetzt werden). Wiederholte Zustellungen werden 24 Stunden lang anhand der external_id oder des Content-Hashs dedupliziert. Siehe Webhook-Trigger.

Dateien

POST /documents/upload (Multipart) mit der Datei sowie source_language, target_language, optionalen target_languages[] und der project_id. DOCX-Roundtrips: Der Export schreibt die Übersetzungen direkt in Ihre Originaldatei zurück, sodass Layout und Styling erhalten bleiben. CSV, PO und XLIFF werden als Key-basierte Einheiten importiert und im jeweiligen Format wieder exportiert. Details zu Formaten und Spaltenmapping: Strings-Dateien.

String-Kataloge

Jeder String ist eine Einheit mit einer stabilen id, einer source sowie optionalen Angaben für context, max_length und placeholders:

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}

Der Kontext wird dem Modell als Anleitung übermittelt, max_length wird per „Shorten-and-Retry“ erzwungen, Platzhalter bleiben geschützt und Pluralformen werden je nach Sprache erweitert. Bereits in der Datei vorhandene Übersetzungen werden kostenlos als aktive Einträge übernommen und speisen das Translation Memory. Fehlen Zielsprachen, schlägt der Aufruf mit no_target_languages fehl, anstatt ein Dokument zu importieren, das in keine Sprache übersetzt wird. Der vollständige Ablauf ist unter Einen String-Katalog über die API lokalisieren beschrieben.

Ein E-Mail-Template, drei Sprachen

Das E-Mail-Beispiel im Detail. Liquid bleibt bei der Übersetzung intakt:

# the template body goes in as HTML; three target languages fan out
curl -s -X POST $BASE/documents \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Trial welcome", "content_type": "html", "source_language": "en",
       "target_languages": ["de", "fr", "uk"],
       "content": "<h1>Welcome, {{ first_name | default:\"friend\" }}!</h1><p>Your trial starts today.</p>"}'

{{ first_name | … }} wird maskiert, bevor das Modell den Text sieht, und anschließend wortgetreu wiederhergestellt. Eine Ausnahme bildet das Fallback friend: Da es sich hierbei um für den Leser sichtbaren Text handelt, wird dieses übersetzt, während der umschließende Tag unverändert bleibt. Führen Sie den Group-Run wie im Quickstart aus und rufen Sie anschließend die einzelnen Sprachen ab:

curl -s "$BASE/documents/<de-version-id>/content?format=html" \
  -H "Authorization: Bearer $KEY"
# → the same HTML with German copy, Liquid intact; paste it into the ESP's de variant

Zero-Touch-Variante: Ein Payload-Webhook-Trigger bezieht das Template direkt vom ESP, der Workflow wird bei Eingang ausgeführt und ein group_run.completed-Webhook gibt das übersetzte HTML zurück. Plattformspezifika (Braze-Tags, Mailchimp-Conditionals): ESP-E-Mail-Templates und der Leitfaden zur E-Mail-Lokalisierung.

Glossare, Styleguides, Translation Memory

Erstellen Sie ein Glossar und fügen Sie im selben Aufruf direkt Begriffe hinzu:

curl -s -X POST $BASE/glossaries \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name": "Product terms", "source_language": "en",
       "terms": [{"source_term": "Transept", "target_term": "Transept",
                  "do_not_translate": true}]}'

Erweitern Sie ein bestehendes Glossar (GET /glossaries listet auf, worauf Ihr Key Zugriff hat):

curl -s -X POST $BASE/glossaries/<id>/terms/bulk \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"terms": [
        {"source_term": "workspace", "target_term": "Arbeitsbereich"},
        {"source_term": "run", "target_term": "Lauf", "notes": "the noun: a workflow execution"}
      ]}'

Oder generieren Sie diese aus einem vertrauenswürdigen Dokument: POST /glossaries/{id}/auto-build und POST /styleguides/generate, jeweils mit einem kostenlosen …/estimate-Pendant. Beide werden pro Wort abgerechnet und erfordern über die API auto_apply: true. Da im Headless-Modus der Review-Schritt entfällt, wird das Ergebnis nach Abschluss sofort übernommen. Fragen Sie den Status über GET /generation-jobs/{id} ab. Die Alternative mit Review in der App: Aus Dokument erstellen. Einmal verknüpft, nutzt sie jeder spätere Durchlauf – ob via API, MCP oder Editor – ohne Zusatzkosten:

curl -s -X PATCH $BASE/documents/<id>/translation-settings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"glossary_ids": ["<glossary_id>"], "styleguide_version_ids": ["<active_version_id>"]}'

Styleguides werden über die active version id verknüpft (abrufbar via GET /styleguides/{id}); [] hebt die Verknüpfung auf; beides funktioniert auch bei POST /documents zum Zeitpunkt der Erstellung. In der Benutzeroberfläche: Glossare, Styleguides. Das Translation Memory muss nicht extra verknüpft werden: Jede abgeschlossene Übersetzung wird automatisch indexiert und wiederverwendet. Fragen Sie es ab (POST /translation-memory/query, kostenlos), befüllen Sie es aus einer TMX/XLIFF-Datei (POST /translation-memory/import, kostenlos) oder exportieren Sie alles (GET /translation-memory/export-tmx). Siehe Translation Memory und Bestehende Übersetzungen importieren.

Teams

Ein Team-Key rechnet über das Team-Guthaben ab und erbt die Projekte, Glossare, Styleguides sowie das Translation Memory des Teams. Erstellen Sie Dokumente im Team, indem Sie die project_id eines Team-Projekts angeben (GET /projects; Team-Projekte verfügen über eine team_id). Alles Weitere entspricht der persönlichen Nutzung. Teams und Projekte werden in der App eingerichtet: Projekte, Teams und Einladungen.

Runs und Review-Gates

POST /runs verarbeitet eine einzelne Sprachversion; POST /group-runs deckt sämtliche Zielsprachen gleichzeitig ab und erstellt bei Bedarf fehlende Versionen. Beide bieten kostenlose Schätzungen, unterstützen den Idempotency-Key und lassen sich abbrechen. Ein Workflow-Schritt, der auf Warten auf Review eingestellt ist, pausiert den Run: GET /runs/{id} meldet gate_pending: true zusammen mit einer Zusammenfassung der Review-Ergebnisse. Die menschliche Seite dieser Pause bilden das Review-Panel und der Guided Review; die Skript-Seite:

# continue downstream steps (all blocks, or a reviewed subset):
curl -s -X POST $BASE/runs/<id>/gate/approve \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"approved_block_ids": ["…"]}'    # omit the field to approve all

# a gate with nothing downstream is dismissed instead:
curl -s -X POST $BASE/runs/<id>/gate/acknowledge -H "Authorization: Bearer $KEY"

Ein Gate setzt den Prozess niemals von sich aus fort: Die Freigabe (approve) muss explizit aufgerufen werden – sei es durch Ihr Skript, einen Assistenten über MCP oder eine Person in der App. Es gibt kein Flag beim Start des Runs, das Gates vorab genehmigt; wenn der Prozess gar nicht pausieren soll, verwenden Sie einen Workflow ohne Review-Schritt.

Ausgabeformate

GET /documents/{id}/content?format=<f> für eine Sprachversions-ID:

format=strings beim Master-Dokument gibt alle Sprachen in einem Aufruf zurück – bereit für den Commit.

Nur das Delta aktualisieren

Übermitteln Sie bei String-Katalogen einfach die gesamte aktuelle Datei erneut; der Server übernimmt die Differenzberechnung (Diff):

# 1: re-import the complete current corpus; Transept 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 > delta.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
jq -n --slurpfile d delta.json \
  '{document_id: $d[0].master_document_id, template_id: "end_to_end",
    target_languages: "all", block_ids: $d[0].delta_block_ids}' \
| curl -s -X POST $BASE/group-runs \
    -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" --data-binary @-

Unveränderte Strings behalten ihre Übersetzungen und ihren Review-Status bei; die Korrektur eines Strings kostet einen String. (Übergeben Sie run: {template_id} beim Re-Import direkt inline, um das Delta im selben Aufruf zu verarbeiten.) Dies ist die API-Entsprechung zu Nur Geändertes ausführen. Bei Fließtext-Dokumenten, deren Quelle sich geändert hat, richtet POST /documents/{id}/resync-source die Blöcke neu aus: Unveränderte Blöcke behalten ihre Übersetzungen, geänderte werden als veraltet markiert, und ein Run für nur aktualisierte Inhalte betrifft lediglich diese. Da der Resync die gespeicherte Quelldatei neu parst, sollten Sie Quellen über den Importweg bearbeiten und nicht durch das Patchen einzelner Blöcke.

KI-Assistenten (MCP)

Hier wird derselbe Ablauf wie bei den Agent-Tools unter https://app.transept.ai/api/public/v1/mcp genutzt: me_get → document_create → group_run_estimate / group_run_start → group_run_get → document_content_get. Die Anbindung erfolgt per OAuth (Zustimmung im Browser, kein Kopieren von Schlüsseln; für Headless-Szenarien kann ein Bearer-Token genutzt werden). Die Tools berücksichtigen die gewährten Berechtigungen. Bei allen Aktionen, die Wörter verbrauchen, wird zunächst eine Schätzung zurückgegeben; der Assistent muss diese explizit bestätigen. Einrichtung pro Client: KI-Assistenten verbinden.

FAQ

Verbrauchen Schätzungen, Re-Importe oder bereits vorhandene Übersetzungen Wörter?

Nein. Schätzungen sind kostenlos und unverbindlich. Auch der Re-Import eines Katalogs ist gratis (die Differenzberechnung erfolgt serverseitig), und bereits in Ihren Dateien enthaltene Übersetzungen werden ohne Anrechnung als fertige Arbeit übernommen. Wörter werden nur dann verbraucht, wenn Transept tatsächlich neue Inhalte für Sie übersetzt. Ursprüngliche Maximalschätzungen werden nach Abschluss auf den tatsächlichen Verbrauch angepasst, wodurch die nicht genutzte Reserve wieder frei wird.

Kann die Automatisierung Review-Gates umgehen?

Nein. Ein Workflow-Schritt, der auf ein Review wartet, pausiert den Durchlauf, bis eine Freigabe erfolgt: entweder durch Ihr Skript, das den Gate-Approve-Endpunkt aufruft, oder durch eine Person in der App. Wenn eine Pipeline komplett unbeaufsichtigt von Anfang bis Ende durchlaufen soll, konfigurieren Sie den Workflow ohne Review-Schritt; es gibt keine Einstellung, mit der sich ein einmal eingerichtetes Gate umgehen lässt.

Ist die API im Free-Tarif verfügbar?

Ja. API-Keys sind in jedem Tarif verfügbar, auch im Free-Tarif; es gibt keine separate Freischaltung. Die Nutzung wird – genau wie im Editor – allein durch Ihr Wortguthaben begrenzt. Das monatliche Kontingent des Free-Tarifs lässt sich über die API genauso nutzen wie an jeder anderen Stelle.

Wie lokalisiere ich E-Mail-Templates, ohne sie manuell exportieren zu müssen?

Verknüpfen Sie Ihre E-Mail-Plattform mit einem Webhook-Trigger: Der per POST übermittelte Body des Templates wird als Dokument angelegt, vom Workflow übersetzt und beim Export erhalten Sie die ursprüngliche HTML-Struktur mit den fertigen Übersetzungen zurück. Platzhalter und Template-Syntax bleiben während des gesamten Vorgangs geschützt. Die Details für die einzelnen Plattformen finden Sie im Leitfaden zur E-Mail-Lokalisierung.

Wo finde ich die vollständige Endpunkt-Referenz?

Die interaktive Swagger-Referenz wird aus derselben OpenAPI-Spezifikation generiert, die Sie auch in n8n, Zapier oder einen Code-Generator importieren können (JSON-Rohdaten). Dieser Leitfaden dient als inhaltliche Einführung; die Spezifikation ist die verbindliche technische Grundlage.