Traduzioni dei modelli

Un modello può essere inviato in più lingue. Ha una lingua predefinita e fino a 29 varianti linguistiche (traduzioni). L’ID del modello resta lo stesso in ogni lingua, quindi il tuo codice aggiunge solo la lingua che vuole – ad esempio locale: 'de' – e Frontmail sceglie la variante giusta.

Va bene qualsiasi lingua, non solo le otto lingue della dashboard: usa un tag di lingua BCP 47 come hu, nl o pt-BR.

Cosa si traduce e cosa è condiviso

Ogni variante ha i propri:

Oggetto,
corpo HTML,
versione testo (generata automaticamente dall’HTML della variante o scritta a mano),
Nome mittente – facoltativo; lascialo vuoto per usare il nome del mittente della lingua predefinita.

Tutto il resto si definisce una sola volta, nella lingua predefinita, ed è comune a tutte le lingue: i destinatari (A, CC, BCC, Reply-To), Email mittente, i parametri, CSS inline al salvataggio, il servizio, le impostazioni di protezione, gli allegati, la risposta automatica e la raccolta contatti.

È una scelta voluta: le regole di sicurezza di un modello – destinatari dinamici, il blocco del contenuto, i campi del mittente fissi e la validazione dei parametri – stanno in un unico posto, così una traduzione non può mai allentarle. Una variante può usare solo parametri che esistono nella lingua predefinita.

Come aggiungere una lingua

Per aggiungere e modificare le traduzioni serve il ruolo Proprietario, Admin o Sviluppatore.

Apri il modello. Sopra le schede dell’editor c’è la barra Lingue con la lingua predefinita (contrassegnata come Predefinita) e un chip per ogni variante.
Clicca su Aggiungi lingua.
In Lingua, scegli una lingua dall’elenco o scrivi il suo codice (ad es. pt-BR) e scegli Usa «pt-BR».
In Parti da, scegli:
- Copia della lingua predefinita – traduci tu il testo,
- Traduzione automatica – tradotta con la chiave del provider della tua organizzazione (vedi Traduzione automatica); scegli il Servizio se ne hai configurato più di uno,
- Vuota – oggetto e HTML vuoti.
Clicca su Aggiungi lingua, traduci o controlla il contenuto e clicca su Salva.

La nuova lingua resta una bozza (contrassegnata come nuova) finché non la salvi. La traduzione automatica usa solo la lingua predefinita salvata – le modifiche non salvate non sono incluse.

Modificare una traduzione

Clicca su una lingua nella barra Lingue per passare l’editor a quella lingua. L’editor mostra Stai modificando la traduzione: … e funziona come al solito:

Contenuto – l’oggetto e le schede HTML, Visuale e Testo modificano la variante. I Dati di esempio e l’anteprima sono condivisi, e l’anteprima mostra la variante esattamente come verrà inviata. I Parametri qui sono in sola lettura (I parametri sono comuni a tutte le lingue. Modificali nella lingua predefinita.).
Impostazioni – solo l’oggetto, il Nome mittente e l’impostazione della versione testo appartengono alla variante; i campi condivisi sono contrassegnati con Comune a tutte le lingue.
Snippet e Invia prova hanno un campo Lingua, così puoi copiare il codice o inviare un’email di prova in qualsiasi lingua.

I Controlli confrontano anche la variante con la lingua predefinita: un parametro che esiste solo nella traduzione è un errore (aggiungilo prima alla lingua predefinita), un parametro usato nella lingua predefinita ma assente nella traduzione è un avviso.

Etichette Non aggiornata e Automatica

Non aggiornata – la lingua predefinita è stata salvata di nuovo dopo questa traduzione, quindi alla traduzione potrebbe mancare qualcosa. L’invio funziona comunque. Aggiorna la traduzione e salvala oppure – se va ancora bene – clicca su Segna come aggiornata.
Automatica – la versione salvata viene dalla traduzione automatica. Controllala prima di farci affidamento.

Con una variante selezionata, la barra offre anche Traduci di nuovo (una nuova traduzione automatica della lingua predefinita salvata; non viene salvato nulla finché non clicchi su Salva) ed Elimina lingua. Quando elimini una lingua, vengono eliminate anche le sue versioni e le email che la richiedono vengono inviate nella lingua predefinita.

Versioni e ripristino

Ogni salvataggio di una traduzione crea una nuova versione di quella traduzione – ogni lingua ha la sua numerazione. Con una variante selezionata, la scheda Versioni mostra Versioni della traduzione … con Basata su (la versione della lingua predefinita su cui è stata salvata) e Origine (Manuale o Automatica). Confronta le versioni e Ripristina una versione precedente proprio come per la lingua predefinita.

Un messaggio registra sempre la lingua e la versione della traduzione con cui è stato generato. Le email che aspettano nella coda dei messaggi in attesa vengono inviate con le versioni che erano attuali quando sono state accettate.

Cambiare la lingua predefinita

La lingua predefinita si trova in Impostazioni → Generale → Lingua predefinita. Puoi scegliere qualsiasi lingua tranne una che ha già una variante – elimina prima quella variante.

Inviare in una lingua

La lingua la sceglie sempre esplicitamente chi invia. Frontmail non la deduce dal browser (Accept-Language) – passa tu la lingua del visitatore quando ti serve.

Come viene scelta la lingua

Per un locale richiesto, Frontmail usa:

nessun locale → la lingua predefinita,
una corrispondenza esatta (maiuscole e minuscole non contano) → quella lingua,
la stessa lingua di base → de-AT riceve de; pt riceve una variante pt-… come pt-BR,
altrimenti → la lingua predefinita.

Una lingua sconosciuta non è un errore – locale è una preferenza. Viene rifiutato con 400 invalid_body solo un tag non valido (ad es. "german!").

La risposta ti dice quale lingua è stata usata davvero:

{ "message_id": "msg_…", "status": "queued", "status_token": "…", "locale": "de" }

API REST

Aggiungi locale a POST /v1/send (e a ogni messaggio di POST /v1/send-batch):

{
  "template_id": "tpl_01J9…",
  "template_params": { "name": "Giulia" },
  "locale": "de"
}

POST /v1/send-form usa il campo riservato del modulo fm_locale. Un campo chiamato locale resta un normale parametro del modello, quindi i moduli esistenti continuano a funzionare:

<select name="fm_locale">
  <option value="it">Italiano</option>
  <option value="de">Deutsch</option>
</select>

SDK

Ogni SDK ha un’opzione locale e restituisce la lingua usata in result.locale.

Browser (@frontmail/browser) – sendForm la invia come fm_locale; un campo fm_locale del modulo stesso ha la precedenza:

const result = await send('svc_01J9…', 'tpl_contact', { name: 'Giulia' }, { locale: 'de' });
await sendForm('svc_01J9…', 'tpl_contact', '#contact', { locale: document.documentElement.lang });
console.log(result.locale); // 'de'

React (@frontmail/react) – la prop locale di <FrontmailForm>, oppure options.locale di send / sendForm. Vue e Svelte funzionano allo stesso modo:

<FrontmailForm serviceId="svc_01J9…" templateId="tpl_contact" locale="de">…</FrontmailForm>

const { send } = useSendEmail('svc_01J9…', 'tpl_contact');
await send({ name: 'Giulia' }, { locale: 'de' });

Node.js (@frontmail/node):

const { locale } = await frontmail.send({ templateId: 'tpl_order', params: { order_id: 'A-1042' }, locale: 'de' });
await frontmail.sendBatch([{ templateId: 'tpl_reminder', params: { name: 'Giulia' }, locale: 'it' }]);

Android / Kotlin (dev.frontmail:frontmail):

val result = frontmail.send(
    "tpl_contact",
    mapOf("name" to name),
    options = SendOptions(locale = Locale.getDefault().toLanguageTag()),
)
println(result.locale) // "de"

iOS / Swift (Frontmail per Swift) – usa Locale.preferredLanguages.first (ad es. de-AT); Locale.current.identifier usa _ e non è un tag valido:

let result = try await frontmail.send(
    templateID: "tpl_contact",
    params: ["name": "Marco"],
    options: SendOptions(locale: Locale.preferredLanguages.first)
)
print(result.locale ?? "default") // "de"

Flutter / Dart (frontmail) – usa toLanguageTag() (ad es. de-AT); Locale.toString() usa _ e non è un tag valido:

final result = await frontmail.send(
  templateId: 'tpl_contact',
  params: {'name': 'Marco'},
  options: SendOptions(locale: Localizations.localeOf(context).toLanguageTag()),
);
print(result.locale ?? 'default'); // "de"

React Native usa send(params, { locale: 'de' }) da useSendEmail. npx frontmail types elenca le lingue di ogni modello e genera un tipo per esse – vedi Node.js.

Risposte automatiche, reinvii ed EmailJS

Le risposte automatiche seguono la lingua del messaggio originale: il modello di risposta automatica sceglie la propria variante per quella lingua con le stesse regole (e ripiega sulla sua lingua predefinita).
Invia di nuovo in Cronologia invia di nuovo il messaggio nella stessa lingua, con la versione attuale della traduzione. Se nel frattempo quella lingua è stata eliminata, viene usata la lingua predefinita.
Le route compatibili con EmailJS (/api/v1.0/email/…) e @frontmail/emailjs-compat inviano sempre la lingua predefinita.

La formattazione segue la lingua dell’email

L’email viene generata nella lingua in cui viene inviata. formatDate, formatNumber e formatMoney formattano date, numeri e importi per quella lingua (una variante tedesca stampa 1. Oktober 2026 e 49,00 €). Il piè di pagina Inviato con Frontmail del piano Free è nella lingua dell’email se è una delle otto lingue della dashboard, altrimenti in inglese.

Traduzione automatica

Frontmail può tradurre un modello per te con OpenAI, Anthropic, Google Gemini o DeepL – usando la chiave API della tua organizzazione («bring your own key»). Frontmail non traduce mai a proprio conto e la traduzione automatica non costa crediti Frontmail; è il provider a fatturare l’utilizzo al tuo account.

La traduzione automatica è sempre manuale: parte solo quando scegli Traduzione automatica in Aggiungi lingua o clicchi su Traduci di nuovo, e il risultato è una bozza che controlli prima di salvarla.

Come configurare la chiave di un provider

Solo proprietari e admin possono aggiungere o modificare le chiavi. Gli sviluppatori vedono quali provider sono configurati (in sola lettura) e possono usarli per tradurre.

Apri Impostazioni → Traduzione automatica.
Accanto al provider, clicca su Aggiungi chiave. Ottieni una chiave … apre la pagina delle chiavi del provider.
Incolla la Chiave API. Per OpenAI, Anthropic e Gemini puoi indicare un Modello (facoltativo); lascialo vuoto per usare il modello predefinito del provider. DeepL non ha una scelta del modello.
Clicca su Salva chiave. Prima di salvarla, Frontmail verifica la chiave con una piccola richiesta al provider.

Con più di un provider, clicca su Imposta come predefinito per scegliere quale viene preselezionato. Sostituisci chiave e Rimuovi si trovano accanto a ogni provider configurato; rimuovere una chiave non elimina le traduzioni già salvate.

La chiave viene conservata cifrata e non viene più mostrata – la dashboard ne mostra solo gli ultimi quattro caratteri. Ogni modifica viene registrata nel registro attività.

Cosa viene inviato al provider

Solo oggetto, HTML, versione testo e nome del mittente della lingua predefinita salvata – la versione testo solo se è scritta a mano (quella automatica viene generata dall’HTML tradotto). Nient’altro lascia Frontmail: né destinatari, né valori dei parametri, né dati di esempio, contatti o cronologia dei messaggi. La richiesta va direttamente dai server di Frontmail all’API ufficiale del provider, e al contenuto si applicano i termini del provider.

Come viene verificato il risultato

Frontmail chiede al provider di lasciare invariate le espressioni Handlebars ({{name}}, {{#if …}}), i tag e gli attributi HTML, i link e gli indirizzi email, e poi lo verifica: la traduzione deve contenere esattamente le stesse espressioni Handlebars e gli stessi URL di link e immagini del testo di partenza. Se non è così, il risultato viene scartato con La traduzione automatica ha modificato parametri, link o struttura HTML, quindi non è stata usata. (translation_invalid) – riprova o usa un altro provider. Non viene salvato nulla in modo parziale.

Altri errori: translation_not_configured (nessuna chiave configurata), translation_provider_auth (il provider ha rifiutato la chiave) e translation_provider_error (il provider ha avuto un problema – riprova più tardi).

Limiti e costi

30 traduzioni automatiche all’ora per organizzazione.
60.000 caratteri di contenuto di partenza per traduzione; i modelli più lunghi ricevono payload_too_large.
Una traduzione ha 60 secondi per completarsi.
I costi vengono addebitati dal provider all’account a cui appartiene la chiave. Tradurre non usa crediti Frontmail, e inviare un’email tradotta costa lo stesso singolo credito di qualsiasi altra.

Limiti

30 lingue per modello – la lingua predefinita più 29 varianti.
Una variante ha gli stessi limiti di dimensione del contenuto del modello.
I tag di lingua possono avere al massimo 35 caratteri.

Esportazione e importazione

Esporta (.json) include tutte le varianti linguistiche e Importa le ricrea nel nuovo modello. I file di esportazione più vecchi senza varianti si importano come prima.