Documentazione

Tradurre contenuti

Contrassegna il contenuto che vuoi tradurre con Magic Translate. Il contenuto originale viene mostrato fino al caricamento della traduzione.

L'elemento <t>

Inserisci il testo in un elemento <t> per tradurlo. Può contenere HTML:

<t>This content will be translated</t>


<t>Click <a href="/sale">here</a> to see <b>today's</b> deals.</t>

Anche <mt-translate> funziona, se preferisci un nome di elemento personalizzato.

L'attributo data-t

Se non riesci ad aggiungere un elemento wrapper, aggiungi data-t all'elemento esistente per tradurne il contenuto:

<title data-t>My online shop</title>


<select>
  <option data-t>Small</option>
  <option data-t>Large</option>
</select>

Attributi

Elenca gli attributi da tradurre in data-t-attrs, separati da spazi:

<input placeholder="Search products" data-t-attrs="placeholder" />


<img src="team.jpg" alt="Our team" title="Say hi" data-t-attrs="alt title" />

Variabili

Inserisci i valori che cambiano, come un nome o un conteggio, in data-v come oggetto JSON e fai riferimento ad essi come $name:

<t data-v='{"name": "Bob", "count": 7}'>Hi $name, you have $count new messages</t>


<input placeholder="Search $count products" data-t-attrs="placeholder" data-v='{"count": 3}' />

Magic Translate traduce il testo attorno ai valori una volta, come Hi {0}, you have {1} new messages, e reinserisce i valori nella pagina. La traduzione è memorizzata nella cache e funziona per ogni nome e conteggio, e i valori stessi non vengono mai inviati a Magic Translate.

Per mostrare nuovi valori, cambia data-v. La traduzione memorizzata nella cache viene riutilizzata e non viene fatta alcuna richiesta:

element.dataset.v = JSON.stringify({ name: 'Bob', count: 8 });

I valori sono numerati nell'ordine in cui appaiono per la prima volta. La traduzione può spostarli ovunque la lingua ne abbia bisogno, ad esempio {1} neue Nachrichten für {0}.

Alcune regole:

  • Vengono sostituite solo le chiavi data-v, quindi un testo come $5 rimane così com'è. Se due tasti iniziano nello stesso modo, ad esempio count e counts, vince quello più lungo.
  • Lo stesso nome può apparire più di una volta.
  • I valori vengono inseriti come testo, mai come HTML. Inserisci invece un markup nel testo che li circonda: Hi <b>$name</b>.
  • Nel contenuto, le variabili vengono sostituite solo nel testo, non in attributi come href o title.
  • Se data-v non è un oggetto JSON valido, il testo non viene tradotto e viene registrato un avviso. Una chiave che non appare nel testo registra anche un avviso.
  • $name è visibile fino al caricamento dello script. Carica lo script all'inizio della pagina o nascondi questi elementi fino ad allora.

Opzioni

Usa questi attributi per impostare le opzioni per un singolo elemento:

AttributoValoreDescrizione
data-formalityinformal o formalImposta la formalità della traduzione.
data-langun codice linguisticoSostituisce la lingua della pagina.
data-t-idun IDTi consente di modificare questo uso del testo da solo. Si applica al contenuto dell'elemento, non al suo data-t-attrs.
<t data-lang="fr" data-formality="formal">How are you?</t>

Contenuti che cambiano

Anche i contenuti aggiunti alla pagina in un secondo momento, o modificati dai tuoi script, vengono tradotti. Funziona per i contenuti renderizzati da JavaScript, ad esempio con htmx o jQuery.

Tutte le traduzioni richieste contemporaneamente vengono inviate all'API in un'unica richiesta e le traduzioni vengono memorizzate nella cache. Puoi contrassegnare tutti gli elementi che desideri.

Limitazioni

Il contenuto di un singolo elemento non può superare i 10 KB, ovvero circa 5.000 caratteri. Gli elementi annidati vengono tradotti come parte dell'elemento <t> principale.

PrecedenteJavaScriptProssimoAPI JavaScript