REST-API und KI-Agenten (SwiftLing Pro)

Dokumentation / Entwickler

Mit SwiftLing Pro können andere Systeme Übersetzungen lesen und schreiben: ein Import von einer Übersetzungsagentur, ein Headless-Editor, ein Skript oder eine App. SwiftLing selbst beantwortet WordPress-Routen in einer bestimmten Sprache und listet die Sprachen auf; siehe docs/rest-api.md von SwiftLing. SwiftLing Pro ergänzt die folgenden Funktionen.

Jede Anfrage erfolgt im Namen eines Benutzers und verwendet die WordPress-Authentifizierung (ein Anwendungspasswort oder Cookie und Nonce eines angemeldeten Benutzers). Sie darf alles tun, was dieser Benutzer im Übersetzungseditor tun darf: Administratoren und Redakteure übersetzen, was sie bearbeiten dürfen; Übersetzer (Einstellungen › Übersetzer) können alles übersetzen, dürfen die Beiträge selbst aber nicht ändern und verwenden daher die Routen von swiftling-pro/v1. Diese Routen arbeiten mit den Originalen, auch unter der Adresse einer Sprache.

Die eigenen Texte eines Beitrags oder Begriffs: swiftling_translations

Beiträge der von SwiftLing übersetzten Inhaltstypen und Begriffe der übersetzten Listen haben ein Feld swiftling_translations, sowohl auf den WordPress-Routen (wp/v2/posts, wp/v2/pages, wp/v2/categories…) als auch auf denen von WooCommerce (wc/v3/products, dessen Produkte Beiträge sind). Nach dem Slug der jeweiligen Sprache:

"swiftling_translations": {
  "de": { "title": "Kontakt", "excerpt": "Schreiben Sie uns", "slug": "kontakt" }
}

Ein Begriff hat name, description und slug. Eine leere Zeichenfolge bedeutet, dass keine Übersetzung vorliegt; bei einem leeren Slug wird der des Originals angezeigt. Ein Text, dessen Original seit der Übersetzung geändert wurde, wird als leer ausgelesen, bis er erneut übersetzt wird. Besucher können nur die Sprachen auslesen, die für sie sichtbar sind; wer übersetzt, kann alle Sprachen auslesen.

Wenn das Feld wie jedes andere Feld zusammen mit dem Beitrag oder Begriff geschrieben wird, speichert es Übersetzungen:

POST /wp-json/wp/v2/posts/12
{ "swiftling_translations": {
    "de": { "title": "Kontakt", "excerpt": "Schreiben Sie uns", "slug": "kontakt",
            "texts": { "8f14e45fceea167a5a36dedd4bea2543": "Rufen Sie uns an" },
            "state": "machine" } } }

• title und excerpt (bei einem Begriff name und description) werden unter ihrem Namen gespeichert; texts enthält die übrigen Texte des Beitrags nach Schlüssel, wie sie GET swiftling-pro/v1/texts auflistet.
• state ist reviewed (die Standardeinstellung) oder machine für eine maschinelle Übersetzung, die noch geprüft werden muss.
• Ein leerer Text entfernt die Übersetzung; bei einem leeren Slug wird wieder der des Originals verwendet.
• Mit der ersten Übersetzung eines Titels erhält der Beitrag seinen Slug in dieser Sprache, sofern kein slug angegeben wird.

Alles wird geprüft, bevor etwas gespeichert wird. Ein Schreibvorgang wird daher entweder vollständig oder gar nicht gespeichert:

Bei den WooCommerce-Routen enthält ein Fehler kein data.keys: WooCommerce gibt ihn in seinem eigenen Format zurück.

Ein Beitrag, der noch nie geprüft wurde, wird zuerst auf dem Server geprüft. Das dauert ein bis zwei Sekunden.

Beliebige Übersetzungsobjekte: swiftling-pro/v1

Ein Übersetzungsobjekt ist das, was der Übersetzungseditor öffnet: einen Beitrag (post:12), ein Template eines Block-Themes (template:twentytwentyfive//archive), einen Seitentyp eines klassischen Themes (view:search), die Begriffe einer Liste (terms:category), ein klassisches Menü (menu:3) oder ein Objekt eines Builders, etwa eine Optionsseite von Advanced Custom Fields.

GET /wp-json/swiftling-pro/v1/texts?subject=post:12&lang=de

Die Texte des Übersetzungsobjekts mit ihren Übersetzungen in die angegebene Sprache, wie sie der Editor auflistet. Die Originale werden nicht gespeichert; daher wird die Seite des Objekts zuerst auf dem Server geprüft.

{
  "subject": { "key": "post:12", "kind": "post", "title": "Kontakt", "url": "https://example.com/kontakt/" },
  "texts": [
    { "key": "1f0e3dad99908345f7439f8ffabdffc4", "object": "post:12", "path": "field/post_title",
      "section": "page", "kind": "heading", "type": "text", "original": "Kontakt",
      "translation": "", "state": "missing", "previous": "", "follows": false }
  ]
}

• type ist text, html, code, url (eine Adresse: ein Link oder ein Bild) oder format, ein Text aus Code, der die Platzhalter seines Originals beibehält.
• state ist reviewed, machine, official (die eigene Übersetzung von WordPress oder des Themes), outdated mit previous, der Übersetzung des Originals vor dessen Änderung, oder missing.
• follows ist eine Menübeschriftung, die den übersetzten Titel der zugehörigen Seite anzeigt, solange sie keine eigene Übersetzung hat.
• Ein Schlüssel bezeichnet den Text und die Version seines Originals: Eine Übersetzung einer älteren Version wird abgelehnt, sobald die Seite seitdem geprüft wurde.

POST /wp-json/swiftling-pro/v1/texts

{ "subject": "post:12", "lang": "de", "state": "reviewed",
  "texts": { "1f0e3dad99908345f7439f8ffabdffc4": "Kontakt" } }

Speichert die Übersetzungen nach Schlüssel, nachdem sie wie die Felder geprüft wurden. Die Antwort enthält die states der gespeicherten Übersetzungen, den Status des Inhalts in jeder Sprache (languages) und bei einem Beitrag dessen address in der jeweiligen Sprache.

POST /wp-json/swiftling-pro/v1/translate

{ "subject": "post:12", "lang": "de" }

Füllt die leeren Texte des Inhalts mithilfe des Übersetzungsdienstes und speichert sie als maschinelle Übersetzungen – so wie „Alles übersetzen“ es für eine Seite tut. Mit "again": ["machine"] (oder reviewed) werden stattdessen Texte in diesen Status erneut übersetzt. Die Antwort enthält die Anzahl aller texts, die Anzahl der translated Texte, deren characters und gegebenenfalls den error des Dienstes, falls er vorzeitig abgebrochen hat: Was zuvor übersetzt wurde, bleibt erhalten. Übersetzer können dies nutzen, sofern es unter Einstellungen › Übersetzer nicht untersagt ist.

GET /wp-json/swiftling-pro/v1/to-translate?lang=de

Was in einer Sprache noch übersetzt werden muss: standardmäßig nicht übersetzte, teilweise übersetzte, veraltete oder nur maschinell übersetzte Inhalte. Die Paginierung entspricht der von WordPress-Routen (page, per_page bis 100, X-WP-Total, X-WP-TotalPages).

[ { "key": "post:12", "kind": "post", "title": "Kontakt", "state": "missing",
    "url": "https://example.com/de/kontakt/", "id": 12, "type": "page" } ]

Für einen Inhalt, der noch nie geprüft wurde, sind noch keine Texte bekannt; sein Status ist daher missing.

Ein Shop: swiftling_prices und swiftling_language

Die WooCommerce-Routen (wc/v3) enthalten zwei zusätzliche Felder.

Produkte und Varianten haben swiftling_prices: den eigenen regulären Preis und Angebotspreis des Produkts in jeder der anderen Währungen des Shops (Einstellungen › Währungen), nach Währungscode. Ein leerer Preis bedeutet, dass kein eigener Preis festgelegt ist; der Preis wird dann aus der Shopwährung umgerechnet.

"swiftling_prices": {
  "USD": { "regular": "12.50", "sale": "" },
  "GBP": { "regular": "", "sale": "" }
}

Bestellungen haben swiftling_language: die Sprache, in der die Bestellung aufgegeben wurde und in der die E-Mails an den Kunden verfasst werden, oder null bei einer im Adminbereich erstellten Bestellung.

"swiftling_language": { "locale": "de_DE", "slug": "de" }

Beide Felder werden zusammen mit dem Produkt oder der Bestellung geschrieben, wie die eigenen Felder von WooCommerce: Preise als Dezimalzahlen in Zeichenfolgen, wie WooCommerce sie schreibt, und nur für die angegebenen Preisarten und Währungen; die Sprache über ihren Slug oder ihre Locale ("de"), wobei sie eine der Sprachen der Website sein muss, einschließlich der Originalsprache. Sie werden geschrieben, bevor WooCommerce speichert. So wird eine über die API erstellte Bestellung mit ihrer Sprache gespeichert, und ihre ersten E-Mails werden in dieser Sprache versendet. Eine Währung, die der Shop nicht führt (swiftling_currency), ein Preis, der keine Zahl ist (swiftling_price), oder eine Sprache, die die Website nicht anbietet (swiftling_language), führt zum Abbruch der Anfrage mit Status 400, bevor etwas davon gespeichert wird.

Funktionen

Where WordPress has the Abilities API (6.9 and later), SwiftLing Pro registers its translation abilities in the category swiftling-translation, for AI agents (through an MCP adapter) and other tools. They are the same steps as the routes above, with the same rights, and run over the Abilities API’s own routes too: GET /wp-json/wp-abilities/v1/abilities/swiftling-pro/get-texts/run?input[subject]=post:12&input[lang]=de.