Transept mit der API automatisieren

Erstellen Sie unter Einstellungen → Entwickler einen persönlichen API-Key. Er ist in jedem Tarif verfügbar, auch im Free-Tarif – es gibt keine separate Hürde, die Nutzung wird allein durch Ihr Wortguthaben begrenzt. Geben Sie dem Key einen Namen, legen Sie optional ein Ablaufdatum fest und kopieren Sie das Secret, sobald es angezeigt wird: Es erscheint nur einmal und kann später nicht mehr abgerufen werden. Widerrufen Sie einen Key jederzeit auf derselben Seite.

Anfragen werden über den Key im Authorization: Bearer tsk_live_…-Header authentifiziert – ausschließlich im Header, niemals in einer URL.

Mit sechs kurzen Aufrufen gelangen Sie vom API-Key zur fertigen Übersetzung. Nur der eigentliche Übersetzungslauf verbraucht Wörter; Kostenvoranschläge sind kostenlos, und ein wiederholter Aufruf mit demselben Idempotency-Key gibt das ursprüngliche Ergebnis zurück, anstatt doppelt abzurechnen.

Dieselben Aufrufe mit ausführlicheren Erläuterungen finden Sie unter transept.ai/developers. Der Leitfaden zur Lokalisierungs-API führt Sie durch den Rest: String-Kataloge, E-Mail-Vorlagen, Glossare, Teams und Review-Gates.

export KEY="tsk_live_…"                          # minted under Settings → Developer
BASE="https://app.transept.ai/api/public/v1"

# 1. Check the key: your account, its permissions, your word balance
curl -s $BASE/me -H "Authorization: Bearer $KEY"

# 2. Create a document; Transept creates one language version per target
curl -s -X POST $BASE/documents \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Welcome email", "content": "# Welcome…", "content_type": "markdown",
       "source_language": "en", "target_languages": ["de", "fr", "uk"]}'

# 3. Estimate: the word cost, free, with no side effects
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"}'

# 4. Run: the same body starts it
curl -s -X POST $BASE/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-1" \
  -d '{"document_id": "<master>", "template_id": "end_to_end", "target_languages": "all"}'

# 5. Wait: poll for per-language progress (or get pushed an event; see below)
curl -s $BASE/group-runs/<group-run-id> -H "Authorization: Bearer $KEY"

# 6. Read each language back in the format you need (the table below lists them)
curl -s "$BASE/documents/<version-id>/content?format=markdown" \
  -H "Authorization: Bearer $KEY"

Erstellen Sie Dokumente aus Rohtext, HTML oder Markdown oder laden Sie eine Datei hoch – unterstützt werden dieselben Formate wie in der App. Sie können auch eine String-Tabelle (.tstrings.json) importieren: ein strukturiertes Format für UI-Texte oder Game-Strings, bei dem jeder String eine Einheit mit festem Key und eigenem Kontext darstellt – einer Notiz dazu, worum es sich handelt, wo der Text erscheint, einer Zeichenbegrenzung und der Bedeutung seiner Platzhalter. All das erreicht das Modell; Platzhalter wie {name} sind vor Löschung oder Umbenennung geschützt, und Pluralformen werden sprachspezifisch erweitert (aus einer englischen Form werden zwei im Deutschen und vier im Ukrainischen). Bereits im Dokument enthaltene Übersetzungen werden kostenlos und unverändert übernommen und fließen direkt in das Translation Memory ein.

Ein Gruppenlauf übersetzt gleichzeitig in mehrere Sprachen. Geben Sie das Dokument, den auszuführenden Workflow oder die Vorlage sowie die Zielsprachen an; Transept erstellt alle fehlenden Sprachversionen und führt den Workflow für jede einzelne aus. Eine einzige ID dient zur Nachverfolgung des gesamten Vorgangs – rufen Sie darüber den Fortschritt der jeweiligen Sprachen ab und prüfen Sie, ob ein Review aussteht.

Bei wiederholten Läufen übermitteln Sie die aktuelle Datei einer String-Tabelle erneut, und Transept analysiert die Änderungen: Unveränderte Strings behalten ihre Übersetzungen (einschließlich bereits abgeschlossener Reviews), und der Lauf verarbeitet nur neue oder tatsächlich geänderte Einheiten – die API-Entsprechung zu Nur Geändertes ausführen. Der gesamte schlüsselbasierte Prozess, vom ersten Import bis hin zu Delta-Läufen, wird in Lokalisierung eines String-Katalogs über die API ausführlich beschrieben.

Anstatt Polling zu nutzen, registrieren Sie eine URL, und Transept sendet ein Event per Push, sobald ein Lauf abgeschlossen wurde oder fehlgeschlagen ist, ein Review zur Ansicht bereitsteht, die Verarbeitung eines Uploads beendet ist oder ein Export bereitliegt. Jede Zustellung enthält einen HMAC-SHA256-Header X-Transept-Signature: t=…,v1=…, damit Ihr Empfänger verifizieren kann, dass die Nachricht tatsächlich von uns stammt. Schlägt der Aufruf eines Endpunkts fehl, wird er mit einem Backoff-Verfahren wiederholt, bevor er deaktiviert wird.

# register once; every matching event is POSTed to your URL, signed
curl -s -X POST $BASE/webhooks \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/transept-events",
       "events": ["group_run.completed", "run.gate_ready", "run.failed"]}'
# → the endpoint, including its ONE-TIME secret; verify X-Transept-Signature with it

Ein Workflow kann auch über eine Notion-Datenbank-Automatisierung gestartet werden: Richten Sie den Webhook der Automatisierung auf die Trigger-URL, und Transept führt den Workflow auf der geänderten Seite aus. Der Haken dabei ist, dass ein Notion-Webhook niemals den Inhalt der Seite überträgt – er meldet nur, welche Seite die Aktion ausgelöst hat. Transept liest diese Seite über Ihre Notion-Verbindung ein. Daher müssen zwei Voraussetzungen erfüllt sein, sonst wird jeder Aufruf mit einem Zugriffsfehler abgelehnt und auf der Trigger-Karte erscheint der Hinweis „Notion-Seite konnte nicht gelesen werden“:

• Notion in Transept verbinden – unter Einstellungen → Integrationen. Das ist die einmalige OAuth-Verknüpfung, über die Transept in Ihrem Namen Lesezugriff erhält.
• Geben Sie die Quelldatenbank innerhalb von Notion für die Integration frei – öffnen Sie die Datenbank (oder Seite), klicken Sie auf das •••-Menü, wählen Sie Verbindungen und fügen Sie Transept hinzu. Die Verknüpfung von Notion in den Einstellungen allein gewährt noch keinen Zugriff auf eine bestimmte Datenbank; ohne diesen Schritt ist die Verbindung zwar aktiv, die Seite bleibt jedoch unlesbar.
• Auslösung bei Eigenschaftsänderungen, nicht nur bei Inhaltsbearbeitungen. Notion-Automatisierungen reagieren auf Änderungen von Eigenschaften (und das Hinzufügen von Seiten). Das reine Bearbeiten des Seiteninhalts allein löst daher unter Umständen nichts aus. Die zuverlässigste Methode ist eine Status-Eigenschaft, die von der Automatisierung überwacht wird – stellen Sie diese um (z. B. auf „Bereit zur Übersetzung“), und genau diese Änderung löst den Trigger aus.

Die vollständige Liste der Endpunkte wird als OpenAPI-Spezifikation veröffentlicht, die Sie in n8n, Zapier oder einen Code-Generator importieren können: Nutzen Sie die interaktive Referenz oder rufen Sie die JSON-Rohdaten ab. Bevorzugen Sie ein Tutorial? Unter transept.ai/developers finden Sie den Quickstart mit Copy-and-paste-Beispielen, und der Leitfaden zur Lokalisierungs-API deckt den gesamten Prozess ausführlich ab. Über die API gestartete Läufe werden auf Wortbasis genau wie im Editor der App abgerechnet.

Ja – Transept bietet einen MCP-Endpunkt, mit dem sich KI-Assistenten verbinden können: https://app.transept.ai/api/public/v1/mcp. Die Verbindung erfolgt über Standard-OAuth: Fügen Sie die URL in Claude Code, Claude Desktop, Cursor oder einen beliebigen MCP-Client ein, und ein Browserfenster bittet Sie um die Freigabe des Zugriffs – Sie müssen keinen Key kopieren (ein API-Key als Bearer-Header funktioniert für CI- und Headless-Setups weiterhin). Der Assistent verfügt dann über Tools für den gesamten Prozess: Dokumente importieren, sprachübergreifende Workflows ausführen, Glossare und Styleguides verwalten, das Translation Memory abfragen und Ergebnisse zurücklesen. Zwei Sicherheitsmechanismen sind integriert: Jedes Tool respektiert die von Ihnen erteilten Berechtigungen, und jede Aktion, die Wörter verbrauchen würde, liefert zunächst eine Wortschätzung – der Assistent muss den Start explizit bestätigen, sodass ein Agent niemals versehentlich Kosten verursacht. Vorgefertigte Setup-Snippets für die einzelnen Clients finden Sie in der App auf der Seite Integrationen; die vollständige Anleitung, vom Zustimmungsbildschirm bis zur Trennung der Verbindung, finden Sie unter KI-Assistenten verbinden.