Vollständige API-Referenz: developer.universally.com enthält die Live-Spezifikation für die Translator API und die Platform API mit jedem Feld, Statuscode und Antwortbeispiel. Diese Seite behandelt, was man darüber wissen sollte.
Senden Sie den HTML-Code einer Seite und erhalten Sie denselben HTML-Code mit übersetztem Text zurück. Dies ist der Endpunkt, den das WordPress-Plugin verwendet, und derjenige, der für jede Plattform verwendet werden sollte, die eine Seite serverseitig rendern kann.
Endpunkt
POST https://translator.universally.com/v1/translate/html
X-API-Key: your_api_key_here
Content-Type: application/json
Anfrage
{
"html": "<html>...</html>",
"targetLanguage": "es",
"sourceUrl": "https://example.com/pricing/",
"parserMode": "auto"
}
| Feld | Erforderlich | Hinweise |
|---|---|---|
html |
ja | Das vollständige Dokument oder ein Fragment. Darf nicht leer sein. |
Zielsprache |
ja | Einer der konfigurierten Variantencodes des Projekts, wie z. B. es, es-419 oder pt-br. Ein Regionencode wie es-mx wird abgelehnt. |
sourceUrl |
ja | Muss eine gültige URL sein und die Domain muss mit der Domain des Projekts übereinstimmen. |
parserMode |
nein | auto oder classic. Standard ist auto. |
sourceUrl ist keine Dekoration. Sie identifiziert, welche Seite übersetzt wird, damit das Ergebnis gespeichert und wiederverwendet werden kann, und sie wird mit der Domain Ihres Projekts abgeglichen. Eine Nichtübereinstimmung gibt TRANSLATION_SOURCE_URL_DOMAIN_MISMATCH zurück.
Antwort
{
"success": true,
"data": {
"translatedHtml": "<html>...</html>",
"metadata": {
"siteId": "site_123",
"siteDomain": "example.com",
"sourceLanguage": "en",
"targetLanguage": "es",
"sourceUrl": "https://example.com/pricing/",
"stringsExtracted": 142,
"stringsTranslated": 142,
"limitReached": false,
"skippedStrings": 0
}
},
"code": "DATA_FETCHED"
}
Geben Sie translatedHtml für den Besucher aus. Die Metadaten sind für Ihre eigene Protokollierung bestimmt und es lohnt sich, sie aufzuzeichnen:
limitReached ist true, wenn das Projekt bei Ankunft der Anfrage bereits sein Wortlimit erreicht hatte oder überschritten hat. Sie erhalten immer noch gültiges HTML und einen 200er-Statuscode, wobei der Text in der Quellsprache überall dort angezeigt wird, wo eine neue Übersetzung benötigt worden wäre. Siehe Nutzungsbeschränkungen.
skippedStrings zählt, was nicht übersetzt wurde. Es ist das einzige Überspringungssignal: Es wird für das Wortlimit gesetzt und für nichts anderes. Ausschlussregeln erscheinen hier nicht, da ausgeschlossener Inhalt entfernt wird, bevor etwas extrahiert wird. Eine vollständig ausgeschlossene Seite wird mit allen Zählern auf Null zurückgegeben.
stringsExtracted im Vergleich zu stringsTranslated weichen routinemäßig voneinander ab, und eine Lücke allein bedeutet nichts Schlechtes. Text, der an mehreren Stellen vorkommt (ein <title>, der auch ein og:title und ein JSON-LD headline ist), Zeichenfolgen, die als unübersetzbar übersprungen werden (eine reine URL, eine E-Mail-Adresse, eine Zahl, ein einzelnes Zeichen) und alles, was das Wortlimit übersprungen hat, sind dafür verantwortlich.
targetLanguage spiegelt die von Ihnen gesendete Variante in Kleinbuchstaben normalisiert wider. Sie wird exakt mit den konfigurierten Varianten des Projekts abgeglichen und nicht aus einer Region aufgelöst. Deshalb gibt es-mx TRANSLATION_TARGET_LANGUAGE_NOT_ALLOWED zurück, während es-419 funktioniert. Siehe Sprachvarianten und regionale Ausrichtung.
Komprimierte Anfragen
Setzen Sie Content-Encoding: gzip und senden Sie den komprimierten Body. Das Größenlimit zählt die Bytes, die Sie senden. Komprimierung ermöglicht es daher, ein großes Dokument durchzulassen.
Grenzen
Der Request Body darf nicht mehr als 5 MB betragen, was der komprimierten Größe bei Verwendung von gzip entspricht. Größere Anfragen geben REQUEST_TOO_LARGE mit dem Status 413 zurück. Siehe API-Fehler und Limits.
Caching auf Ihrer Seite
Die Antwort wird auf unserer Seite gespeichert, sodass eine wiederholte Anfrage für dieselbe Seite und Sprache schnell erfolgt und keine Wörter mehr verbraucht. Es ist immer noch ein Netzwerk-Roundtrip.
Zwischenspeichern Sie die übersetzte HTML in Ihrer eigenen Ebene, wie es das WordPress-Plugin tut. Das ist der Unterschied zwischen einer schnellen Seite und einer einigermaßen schnellen. Siehe Performance und Seitengeschwindigkeit.
Wenn eine Seite ausgeschlossen ist
Wenn der Pfad mit einer Ausschlussregel für Seiten übereinstimmt, gibt der Endpunkt erfolgreich mit dem ursprünglichen HTML anstelle eines Fehlers zurück. Überprüfen Sie die Metadaten, wenn Sie die beiden unterscheiden müssen. Siehe Seiten ausschließen.