REST-API-Übersicht

Universally stellt eine REST-API zur Übersetzung von Webinhalten in über 110 Sprachen bereit. Die API ist plattformunabhängig: Jedes System, das eine HTTPS-Anfrage stellen kann, kann Inhalte senden und Übersetzungen zurückerhalten. Das offizielle WordPress-Plugin basiert auf derselben API, aber nichts hier ist WordPress-spezifisch.

Verwenden Sie die API, wenn Sie die Übersetzung direkt in Ihren eigenen Stack integrieren möchten: ein benutzerdefiniertes CMS, ein Headless-Frontend, einen Edge-Worker, eine mobile oder Web-App oder jeden Ort, an den das Plugin nicht gelangen kann.

Da wir derzeit nur die WordPress-Integration offiziell unterstützen, ist dies eher ein allgemeiner Überblick über die API, der die Erweiterung des Plugins ermöglichen soll.

Zwei Dienste

Die API ist auf zwei separate Hosts aufgeteilt. Jeder besitzt einen bestimmten Satz von Endpunkten, sodass der Host angibt, welche Funktion Sie aufrufen.

Übersetzerdienst

https://translator.universally.com

Hier findet die gesamte Übersetzung statt. Die meisten Integrationen rufen nur diesen Dienst auf.

Methode	Endpunkt	Beschreibung
POST	/v1/translate/html	Übersetzen eines vollständigen HTML-Dokuments
POST	/v1/translate/strings	Übersetzen eines Arrays von Zeichenfolgen (keine URL erforderlich)
POST	/v1/translate	HTML oder Zeichenfolgen werden aus dem Anfragetext automatisch erkannt
GET	/health	Zustandsprüfung (keine Authentifizierung)

API-Dienst

https://api.universally.com

Dieser Dienst stellt Referenzdaten auf Kontoebene bereit. Sie benötigen ihn nicht zum Übersetzen; er unterstützt die Einrichtung und die Sprachauswahl.

Dies ist derzeit für die öffentliche Nutzung sehr eingeschränkt.

Authentifizierung in Kürze

Jede Anfrage wird mit einem einzigen API-Schlüssel authentifiziert, der im Header X-API-Key gesendet wird. Ihr Schlüssel ist eine 64 Zeichen lange Zeichenfolge, die pro Website über Ihr Universally-Dashboard ausgestellt wird, und derselbe Schlüssel funktioniert bei beiden Diensten. Da der Schlüssel Ihr Übersetzungsguthaben aufbrauchen kann, bewahren Sie ihn serverseitig auf.

X-API-Key: your_api_key_here
Content-Type: application/json

Antwort-Envelope

Jeder Endpunkt gibt dieselbe JSON-Hülle zurück, unabhängig davon, ob die Anfrage erfolgreich ist oder fehlschlägt:

{
  "success": true,
  "data": { },
  "message": "Human-readable message or null",
  "code": "MACHINE_READABLE_CODE"
}

• success ist true für 2xx-Antworten und false für Fehler.
• data enthält die Nutzlast bei Erfolg und ist bei Fehlern null.
• code ist eine stabile, maschinenlesbare Kennung, an der Sie Verzweigungen vornehmen können. Bevorzugen Sie sie gegenüber dem Parsen von message.

HTML oder Zeichenfolgen: Welchen Endpunkt soll ich verwenden?

Der Übersetzer bietet zwei Möglichkeiten zur Übersetzung, abhängig von der Form Ihres Inhalts.

Verwenden Sie /v1/translate/html, wenn Sie eine gerenderte Seite haben. Sie senden ein vollständiges HTML-Dokument zusammen mit seiner kanonischen URL. Universally extrahiert jede übersetzbare Zeichenfolge, einschließlich Textkörper, Meta-Tags, Open-Graph-Daten, strukturierte Daten, Bild-Alt-Texte und Formularattribute, übersetzt sie, lokalisiert Links und gibt das neu geschriebene HTML zurück. Dies ist die richtige Wahl für serverseitig gerenderte Seiten und Edge-Integrationen.

Verwenden Sie /v1/translate/strings, wenn Sie einzelne Textteile haben. Sie senden ein Array von Zeichenfolgen und erhalten eine Zuordnung von Original- zu übersetztem Text. Es ist keine URL erforderlich, daher ist dies die richtige Wahl für Inhalte, die nicht an eine Seite gebunden sind: dynamische Inhalte, die über AJAX geladen werden, benutzergenerierte Texte wie Kommentare und Bewertungen, App-Inhalte, Push-Benachrichtigungen oder jedes Fragment, das Ihre Rendering-Pipeline im laufenden Betrieb erzeugt.

Wenn Sie sich nicht sicher sind, senden Sie die Anfrage an /v1/translate und Universally leitet sie basierend auf dem von Ihnen bereitgestellten Body an den richtigen Handler weiter.

Beispiele

Beide Übersetzungsmethoden befinden sich im Translator-Dienst und werden mit Ihrem API-Schlüssel im X-API-Key-Header authentifiziert.

HTML übersetzen

Senden Sie eine gerenderte Seite und ihre kanonische URL; erhalten Sie das übersetzte Dokument zurück.

curl -X POST https://translator.universally.com/v1/translate/html \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<!DOCTYPE html><html><head><title>Welcome</title></head><body><h1>Hello world</h1></body></html>",
    "targetLanguage": "fr",
    "sourceUrl": "https://example.com/welcome"
  }'

Antwort:

{
  "success": true,
  "data": {
    "translatedHtml": "<!DOCTYPE html><html lang=\"fr\"><head><title>Bienvenue</title></head><body><h1>Bonjour le monde</h1></body></html>",
    "metadata": {
      "siteId": "site_123",
      "siteDomain": "example.com",
      "sourceLanguage": "en-us",
      "targetLanguage": "fr",
      "sourceUrl": "https://example.com/welcome/",
      "stringsExtracted": 2,
      "stringsTranslated": 2,
      "limitReached": false,
      "skippedStrings": 0
    }
  },
  "message": "Data retrieved successfully.",
  "code": "DATA_FETCHED"
}

Strings übersetzen

Senden Sie ein Array von Strings; erhalten Sie eine Zuordnung von Original zu übersetztem Text. Keine URL erforderlich.

curl -X POST https://translator.universally.com/v1/translate/strings \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "strings": ["Welcome back", "Add to cart"],
    "targetLanguage": "fr"
  }'

Antwort:

{
  "success": true,
  "data": {
    "translations": {
      "Welcome back": "Bon retour",
      "Add to cart": "Ajouter au panier"
    },
    "metadata": {
      "sourceLanguage": "en-us",
      "targetLanguage": "fr",
      "stringsReceived": 2,
      "stringsTranslated": 2,
      "limitReached": false,
      "skippedStrings": 0
    }
  },
  "message": "Data retrieved successfully.",
  "code": "DATA_FETCHED"
}

So funktioniert das Caching

Universally speichert jede Übersetzung, die es erstellt, im Cache, sodass Sie niemals zweimal für denselben Inhalt berechnet werden.

• HTML-Übersetzungen werden pro Seite und Sprache im Cache gespeichert. Wiederholte Anfragen für dieselbe URL und Zielsprache geben das zwischengespeicherte Ergebnis sofort zurück, und nur neu geänderte Strings werden zur Übersetzung gesendet.
• String-Übersetzungen werden pro einzelnem String im Cache gespeichert. Sobald ein String für eine bestimmte Sprache übersetzt wurde, wird er bei jeder zukünftigen Anfrage aus dem Cache abgerufen, unabhängig davon, auf welcher Seite oder in welchem Kontext er erscheint.

Sie müssen dies nicht verwalten. Senden Sie Ihren Inhalt bei jeder Anfrage und Universally gibt verfügbare zwischengespeicherte Übersetzungen zurück und übersetzt nur, was neu ist.