Panoramica API REST

Universally espone un'API REST per la traduzione di contenuti web in oltre 110 lingue. L'API è indipendente dalla piattaforma: qualsiasi sistema in grado di effettuare una richiesta HTTPS può inviare contenuti e ricevere traduzioni. Il plugin ufficiale per WordPress è costruito su questa stessa API, ma nulla qui è specifico di WordPress.

Utilizza l'API quando desideri integrare la traduzione direttamente nel tuo stack: un CMS personalizzato, un frontend headless, un edge worker, un'app mobile o web, o qualsiasi luogo in cui il plugin non può arrivare.

Ma poiché attualmente supportiamo ufficialmente solo l'integrazione con WordPress, questa è più una panoramica generale dell'API che dovrebbe consentire di estendere il plugin.

Due servizi

L'API è suddivisa tra due host separati. Ognuno possiede un set distinto di endpoint, quindi l'host ti dice quale funzionalità stai chiamando.

Servizio di traduzione

https://translator.universally.com

È qui che avviene tutta la traduzione. La maggior parte delle integrazioni chiama solo questo servizio.

Metodo	Endpoint	Descrizione
POST	/v1/translate/html	Traduci un documento HTML completo
POST	/v1/translate/strings	Traduci un array di stringhe (nessun URL richiesto)
POST	/v1/translate	Rileva automaticamente HTML o stringhe dal corpo della richiesta
GET	/health	Controllo di integrità (nessuna autenticazione)

Servizio API

https://api.universally.com

Questo servizio fornisce dati di riferimento a livello di account. Non ne hai bisogno per tradurre; supporta la configurazione e la selezione della lingua.

Attualmente è molto limitato per l'uso pubblico.

Autenticazione in breve

Ogni richiesta viene autenticata con una singola chiave API inviata nell'intestazione X-API-Key. La tua chiave è una stringa di 64 caratteri emessa per sito dalla tua dashboard Universally, e la stessa chiave funziona su entrambi i servizi. Poiché la chiave può spendere il tuo budget di traduzione, tienila lato server.

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

Envelope della risposta

Ogni endpoint restituisce lo stesso inviluppo JSON, sia che la richiesta abbia successo o fallisca:

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

• success è true per le risposte 2xx e false per gli errori.
• data contiene il payload in caso di successo ed è null in caso di errore.
• code è un identificatore stabile e leggibile dalla macchina su cui puoi basare delle diramazioni. Preferiscilo all'analisi di message.

HTML o stringhe: quale endpoint devo usare?

Il Translator offre due modi per tradurre, a seconda della forma del tuo contenuto.

Utilizza /v1/translate/html quando hai una pagina renderizzata. Invia un documento HTML completo insieme al suo URL canonico. Universally estrae ogni stringa traducibile, inclusi testo del corpo, meta tag, dati Open Graph, dati strutturati, testo alternativo delle immagini e attributi dei moduli, li traduce, localizza i collegamenti e restituisce l'HTML riscritto. Questa è la scelta giusta per pagine renderizzate lato server e integrazioni edge.

Utilizza /v1/translate/strings quando hai pezzi di testo discreti. Invia un array di stringhe e ricevi una mappa dal testo originale a quello tradotto. Non è richiesto alcun URL, quindi questa è la scelta giusta per contenuti non legati a una pagina: contenuti dinamici caricati tramite AJAX, testo generato dall'utente come commenti e recensioni, contenuti di app, notifiche push o qualsiasi frammento prodotto al volo dalla tua pipeline di rendering.

Se non sei sicuro, invia la richiesta a /v1/translate e Universally la inoltrerà all'handler corretto in base al corpo fornito.

Esempi

Entrambi i metodi di traduzione si trovano nel servizio Translator e si autenticano con la tua chiave API nell'header X-API-Key.

Traduci HTML

Invia una pagina renderizzata e il suo URL canonico; ricevi indietro il documento tradotto.

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"
  }'

Risposta:

{
  "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"
}

Traduci stringhe

Invia un array di stringhe; ricevi una mappa dal testo originale a quello tradotto. Nessun URL richiesto.

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"
  }'

Risposta:

{
  "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"
}

Come funziona la cache

Universally memorizza nella cache ogni traduzione che produce, quindi non ti viene mai addebitato due volte lo stesso contenuto.

• Le traduzioni HTML vengono memorizzate nella cache per pagina e lingua. Richieste ripetute per lo stesso URL e la stessa lingua di destinazione restituiscono il risultato memorizzato nella cache istantaneamente, e solo le stringhe modificate di recente vengono inviate per la traduzione.
• Le traduzioni delle stringhe vengono memorizzate nella cache per singola stringa. Una volta che una stringa è stata tradotta per una determinata lingua, viene servita dalla cache in ogni richiesta futura, indipendentemente dalla pagina o dal contesto in cui appare.

Non è necessario gestire questo. Invia il tuo contenuto ad ogni richiesta e Universally restituirà le traduzioni memorizzate nella cache dove disponibili e tradurrà solo ciò che è nuovo.