Traduci stringhe

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 un array di stringhe, ottieni una mappa dal testo sorgente alla traduzione. Usalo quando hai testo piuttosto che una pagina: un'interfaccia di app, un payload CMS headless, testo di email o notifiche push.

Endpoint

POST https://translator.universally.com/v1/translate/strings
X-API-Key: your_api_key_here
Content-Type: application/json

Richiesta

{
  "strings": ["Add to cart", "Out of stock", "Free shipping over $50"],
  "targetLanguage": "de",
  "fresh": false
}

Campo	Richiesto	Note
stringhe	sì	Tra 1 e 500 voci. Ognuna deve essere non vuota.
lingua di destinazione	sì	Un codice lingua abilitato nel progetto
fresco	no	true ignora le traduzioni memorizzate e traduce di nuovo. Il valore predefinito è false.

Nota che qui non c'è sourceUrl, a differenza di Traduci HTML. Le stringhe non sono legate a una pagina.

Risposta

{
  "success": true,
  "data": {
    "translations": {
      "Add to cart": "In den Warenkorb",
      "Out of stock": "Nicht auf Lager",
      "Free shipping over $50": "Kostenloser Versand ab 50 $"
    },
    "metadata": {
      "sourceLanguage": "en",
      "targetLanguage": "de",
      "stringsReceived": 3,
      "stringsTranslated": 3,
      "limitReached": false,
      "skippedStrings": 0
    }
  },
  "code": "DATA_FETCHED"
}

translations è indicizzato dalla tua stringa originale, quindi puoi cercarne ognuna senza tenere traccia dell'ordine dell'array.

Gestisci chiavi mancanti

Una stringa che non è stata tradotta viene omessa completamente da translations. Cerca ogni chiave con un fallback al tuo testo:

const out = strings.map((s) => data.translations[s] ?? s);

Tre cose causano la mancanza di una chiave:

• Niente da tradurre. Un semplice numero, un URL, un indirizzo email, un singolo carattere.
• La parola totale è esaurita. L'area di lavoro era già al suo limite o oltre quando la richiesta è arrivata, cosa che la risposta riporta come limitReached: true con un conteggio skippedStrings.
• Un fallimento transitorio nella traduzione di quel batch.

Leggi metadata per la forma di ciò che è accaduto: stringsTranslated inferiore a stringsReceived significa che alcune sono assenti.

C'è un caso speciale che si comporta diversamente: se nulla nella richiesta era traducibile, ogni input viene restituito invariato. Non basarti su questo, poiché non si applica non appena una stringa è traducibile.

Deduplicazione

Le stringhe ripetute in una richiesta vengono tradotte una sola volta. Inviare la stessa etichetta cinquanta volte costa una traduzione, quindi non è necessario deduplicare prima di chiamare.

Limiti

500 stringhe per richiesta. Oltre tale limite la validazione fallisce. Dividi set più grandi tra le richieste. Si applica anche il limite di 5 MB del corpo. Vedi Errori e limiti API.

Le regole del glossario si applicano

Le regole del glossario vengono applicate alle stringhe nello stesso modo in cui vengono applicate alle pagine, quindi un termine che traduci sempre o mai si comporta in modo coerente tra entrambi gli endpoint. Vedi Regole del glossario.

Quando usare fresh

Lascialo false. Le traduzioni memorizzate vengono restituite istantaneamente e non costano nulla.

fresh: true traduce nuovamente la stringa e restituisce il nuovo testo senza memorizzarlo, quindi è un'anteprima piuttosto che un modo per modificare ciò che viene servito. La successiva richiesta ordinaria per quella stringa restituisce ancora la traduzione memorizzata in precedenza. Poiché nulla viene memorizzato, una chiamata fresh non viene conteggiata nel totale delle parole.

Per modificare ciò che viene servito, salvare la nuova dicitura nella schermata Traduzioni. Vedere Modifica manuale delle traduzioni.

Correlati

• Traduci HTML
• Autenticazione con l'API
• Errori e limiti dell'API