Transept mit der API automatisieren

Erstellen Sie unter Einstellungen → Entwickler einen persönlichen API-Schlüssel. Er ist in jedem Tarif verfügbar, auch im kostenlosen – es gibt keine separate Freischaltung, die Nutzung wird allein durch Ihr Wörter-Guthaben begrenzt. Geben Sie dem Schlüssel 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. Auf derselben Seite können Sie einen Schlüssel jederzeit widerrufen.

Authentifizieren Sie Anfragen mit dem Schlüssel in einem Authorization: Bearer tsk_live_…-Header – nur im Header, niemals in einer URL.

Erstellen Sie ein Dokument aus Rohtext, HTML oder Markdown oder laden Sie eine Datei hoch – dieselben Formate, die auch die App akzeptiert. 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 einem stabilen Schlüssel und eigenem Kontext ist – ein Hinweis darauf, was es ist, wo es erscheint, ein Zeichenlimit und die Bedeutung der Platzhalter. All das erreicht das Modell; Platzhalter wie {name} sind davor geschützt, gelöscht oder umbenannt zu werden, und Pluralformen werden je nach Sprache erweitert (eine englische Form wird zu zwei im Deutschen, vier im Ukrainischen). Bereits in der Datei vorhandene Übersetzungen werden unverändert und kostenlos übernommen und fließen direkt in das Translation Memory ein.

Ein Gruppen-Run übersetzt in mehrere Sprachen gleichzeitig. Geben Sie das Dokument, den auszuführenden Workflow oder das Template sowie die Zielsprachen an; Transept erstellt alle fehlenden Sprachversionen und führt den Workflow für jede einzelne aus. Eine einzige ID trackt den gesamten Vorgang – fragen Sie diese ab, um den Fortschritt der jeweiligen Sprache zu prüfen und zu sehen, ob eine Überprüfung aussteht.

Bei wiederholten Runs reichen Sie einfach die aktuelle Datei einer String-Tabelle erneut ein, und Transept ermittelt die Änderungen: Unveränderte Strings behalten ihre Übersetzungen (und bereits erfolgte Überprüfungen), und der Run betrifft nur die neuen oder tatsächlich geänderten Einheiten – die API-Entsprechung zu Nur Geändertes ausführen. Ein Aufruf, der einen Auftrag erstellt, akzeptiert zudem einen Idempotency-Key-Header; so gibt ein erneuter Versuch nach einer kurzen Netzstörung das ursprüngliche Ergebnis zurück, statt ein zweites Dokument und eine zweite Abrechnung zu erzeugen.

Statt Polling zu nutzen, registrieren Sie eine URL, und Transept sendet per Push ein Event, wenn ein Run abgeschlossen wird oder fehlschlägt, eine Überprüfung ansteht, ein Upload fertig verarbeitet wurde oder ein Export bereitsteht. Jede Zustellung enthält einen HMAC-SHA256-X-Transept-Signature: t=…,v1=…-Header, damit Ihr Empfänger verifizieren kann, dass sie wirklich von uns stammt. Bei Fehlern wird die Zustellung mit einem Backoff-Verfahren wiederholt, bevor der Endpunkt deaktiviert wird.

Ein Workflow kann auch über eine Notion-Datenbank-Automatisierung automatisch gestartet werden: Richten Sie den Webhook der Automatisierung auf die Trigger-URL aus, und Transept führt den Workflow auf der geänderten Seite aus. Der Haken ist, dass ein Notion-Webhook niemals den Seiteninhalt überträgt – er meldet lediglich, welche Seite ausgelöst wurde. Transept liest diese Seite über Ihre Notion-Verbindung aus. Daher müssen zwei Voraussetzungen erfüllt sein, da sonst jede Auslösung mit einem Zugriffsfehler abgewiesen wird und die Trigger-Karte den Hinweis „Notion-Seite konnte nicht gelesen werden“ anzeigt:

• Verbinden Sie Notion in Transept – unter Einstellungen → Integrationen. Das ist die einmalige OAuth-Verknüpfung, mit der Sie Transept den Lesezugriff in Ihrem Namen erlauben.
• 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. Notion in den Einstellungen zu verbinden, gewährt allein noch keinen Zugriff auf eine spezifische Datenbank; ohne diesen Schritt ist die Verbindung zwar aktiv, die Seite bleibt jedoch unlesbar.
• Auslösung durch Eigenschaftsänderungen statt nur durch Inhaltsbearbeitung. Notion-Automatisierungen reagieren auf geänderte Eigenschaften (und neue Seiten); das Bearbeiten des Seiteninhalts allein löst unter Umständen nichts aus. Am zuverlässigsten funktioniert eine Status-Eigenschaft, die von der Automatisierung überwacht wird: Ändern Sie diese (z. B. auf „Bereit zur Übersetzung“), und genau diese Änderung aktiviert den Trigger.

Die vollständige Liste der Endpunkte wird als OpenAPI-Spezifikation veröffentlicht, die Sie in n8n, Zapier oder einen Code-Generator importieren können: Sehen Sie sie unter /public/v1/docs in Ihrer Transept-API ein oder rufen Sie das JSON-Format unter /public/v1/openapi.json ab. Über die API gestartete Runs rechnen Wörter exakt so ab wie der Editor in der App.