Riferimento API completo: developer.universally.com contiene la specifica live sia per la Translator API che per la Platform API, con ogni campo, codice di stato ed esempio di risposta. Questa pagina copre ciò che vale la pena sapere al riguardo.
Invia l'HTML di una pagina e ricevi indietro lo stesso HTML con il testo tradotto. Questo è l'endpoint utilizzato dal plugin WordPress e quello da utilizzare per qualsiasi piattaforma in grado di renderizzare una pagina lato server.
Endpoint
POST https://translator.universally.com/v1/translate/html
X-API-Key: your_api_key_here
Content-Type: application/json
Richiesta
{
"html": "<html>...</html>",
"targetLanguage": "es",
"sourceUrl": "https://example.com/pricing/",
"parserMode": "auto"
}
| Campo | Richiesto | Note |
|---|---|---|
html |
sì | L'intero documento o un frammento. Non deve essere vuoto. |
lingua di destinazione |
sì | Uno dei codici di variante configurati nel progetto, come es, es-419 o pt-br. Un codice regionale come es-mx viene rifiutato |
URL di origine |
sì | Deve essere un URL valido e il suo dominio deve corrispondere al dominio del progetto |
modalità parser |
no | auto o classic. Il valore predefinito è auto. |
sourceUrl non è una decorazione. Identifica quale pagina viene tradotta in modo che il risultato possa essere memorizzato e riutilizzato, ed è verificato rispetto al dominio del tuo progetto. Una mancata corrispondenza restituisce TRANSLATION_SOURCE_URL_DOMAIN_MISMATCH.
Risposta
{
"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"
}
Serve translatedHtml al visitatore. I metadati sono per il tuo logging e vale la pena registrarli:
limitReached è true quando il progetto era già al limite o oltre il suo conteggio totale di parole al momento della richiesta. Ricevi comunque HTML valido e un codice 200, con il testo nella lingua di origine ovunque sarebbe stata necessaria una nuova traduzione. Vedi Limiti di utilizzo.
skippedStrings conta ciò che è rimasto non tradotto. È l'unico segnale di salto: viene impostato per il limite di parole e nient'altro. Le regole di esclusione non compaiono qui, poiché il contenuto escluso viene rimosso prima che venga estratto qualsiasi elemento. Una pagina interamente esclusa viene restituita con tutti i contatori a zero.
stringsExtracted rispetto a stringsTranslated differiscono regolarmente, e una discrepanza da sola non significa che qualcosa sia andato storto. Il testo che appare in più punti (un <title> che è anche un og:title e un headline JSON-LD), le stringhe che vengono saltate perché non traducibili (un URL semplice, un indirizzo email, un numero, un singolo carattere) e qualsiasi cosa saltata dal limite di parole ne tengono conto.
targetLanguage ripete la variante che hai inviato, normalizzata in minuscolo. Viene confrontata esattamente con le varianti configurate nel progetto anziché essere risolta da una regione, motivo per cui es-mx restituisce TRANSLATION_TARGET_LANGUAGE_NOT_ALLOWED mentre es-419 funziona. Vedi Varianti linguistiche e targeting regionale.
Richieste compresse
Imposta Content-Encoding: gzip e invia il corpo compresso. Il limite di dimensioni conta i byte inviati, quindi la compressione consente di superare un documento di grandi dimensioni.
Limiti
Il corpo della richiesta non può superare i 5 MB così come inviato, che è la dimensione compressa quando si utilizza gzip. Un valore superiore restituisce REQUEST_TOO_LARGE con stato 413. Vedi Errori e limiti dell'API.
Caching dal tuo lato
La risposta viene memorizzata dalla nostra parte, quindi una richiesta ripetuta per la stessa pagina e lingua è veloce e non consuma nuovamente parole. È comunque un viaggio di andata e ritorno di rete.
Memorizza nella cache l'HTML tradotto nel tuo livello, come fa il plugin di WordPress. Questa è la differenza tra una pagina veloce e una pagina abbastanza veloce. Vedi Prestazioni e velocità della pagina.
Quando una pagina è esclusa
Se il percorso corrisponde a una regola di Pagine escluse, l'endpoint restituisce correttamente l'HTML originale anziché un errore. Controlla i metadati se devi distinguere i due. Vedi Pagine escluse.