Un prodotto, molti clienti: traduzioni per cliente con i tenant, un esempio pratico

Le traduzioni per cliente (dette anche override dei tenant) permettono a un prodotto di parlare la lingua di ogni cliente, in senso letterale e commerciale: la stessa app dice "paziente" per uno studio e "cliente" per un altro, indica qui una politica di cancellazione di 24 ore e lì una di 48, e mostra il nome del cliente invece del vostro, mentre tutto il resto resta un unico insieme condiviso di traduzioni. Questo articolo confronta i modi in cui i team lo costruiscono, poi ripercorre un’esecuzione reale: un progetto base, tre tenant cliente, i loro override, cosa è successo quando il testo base è cambiato, e come l’app carica il cliente giusto.

Cinque modi in cui i team gestiscono le formulazioni per cliente

I primi quattro non richiedono strumenti particolari, e il secondo è una configurazione i18next perfettamente valida per pochi clienti. Il resto dell’articolo riguarda il quinto, in cui un cliente in più è un tenant in più, non una copia in più.

L’esempio

ClinicDesk è un’app per gli appuntamenti degli studi, venduta in white-label. I suoi tre clienti sono inventati per questo esempio:

Il progetto base ha 15 chiavi in inglese, tedesco e francese (il francese aggiunge una forma plurale).

Passo 1: il progetto base

La base contiene le formulazioni del prodotto stesso: navigazione, pulsanti, il flusso di prenotazione, un SMS di promemoria, la politica di cancellazione. Abbiamo segnalato le 15 chiavi inglesi con una frase di contesto ciascuna, e la traduzione automatica ha compilato tedesco e francese. Per esempio, la politica è diventata "Sie können bis zu 24 Stunden vor Ihrem Termin kostenfrei stornieren." e "Vous pouvez annuler sans frais jusqu'à 24 heures avant votre rendez-vous."

Passo 2: un tenant per cliente

Nella pagina multi-tenant del progetto, ogni cliente riceve un tenant: un progetto suo, creato dalla base. Con can’t deviate from parent attivo (l’impostazione predefinita), un tenant ha sempre le lingue e i namespace della base, quindi una nuova lingua nella base compare in ogni tenant.

Ogni tenant ha il proprio ID di progetto, i propri utenti e le proprie chiavi API. Le persone di un cliente possono essere invitate solo al loro tenant e non vedono gli altri clienti; il vostro team, in quanto membri della vostra organizzazione, li raggiunge tutti.

Passo 3: le formulazioni di ogni cliente

Gli override sono normali modifiche dentro il tenant: nell’editor, tramite l’API oppure, come qui, tramite il server MCP. Abbiamo scritto gli override inglesi per ogni cliente: sei per Physio North, tre per Praxis am See, uno per Smile Dental:

Una cosa che non avevamo previsto: appena salvati gli override inglesi di Physio North, la traduzione automatica del tenant ne ha ricavato bozze in tedesco e francese, ognuna con un punteggio di confidenza e contrassegnata per la revisione. Abbiamo riscritto la frase di supporto in entrambe le lingue e lasciato le altre cinque bozze alla revisione del cliente. La politica di 48 ore di Praxis am See è stata tradotta in bozza allo stesso modo ("48 heures" in francese); abbiamo tenuto la bozza francese e sostituito quella tedesca. Succede quando il tenant ha la traduzione automatica attiva (al momento della creazione prende l’impostazione dalla base) e l’override arriva tramite l’API, la CLI o MCP come una chiave che il tenant non aveva ancora; un override digitato nell’editor, o una seconda modifica a un override esistente, non viene tradotto in bozza a meno che non richiediate una traduzione.

Nell’editor del tenant, il filtro overridden elenca ogni override, bozze automatiche comprese:

Passo 4: la base cambia

Poi abbiamo cambiato un testo base: la frase di supporto inglese è diventata "Questions? Our support team replies within one business day.", inviata richiedendo la traduzione automatica, quindi tedesco e francese sono stati tradotti di nuovo. (Senza quella richiesta, un testo sorgente modificato mantiene le sue traduzioni e le contrassegna per la revisione.) Due tenant sovrascrivono quella chiave, uno no:

• Smile Dental (nessun override) ha mostrato subito la nuova frase, in tedesco "Haben Sie Fragen? Unser Support-Team antwortet Ihnen innerhalb eines Werktages.", e i suoi file sulla CDN la contenevano senza che nessuno pubblicasse il tenant (la versione pubblica automaticamente; altrimenti il tenant viene ripubblicato quando pubblicate la base).
• Physio North e Praxis am See hanno mantenuto le proprie frasi. Una lettura raw del tenant (da parte di chi ha accesso alla base) mostra accanto a ogni override quale valore base sostituisce, così un agente o uno script può confrontarli.

È questa la regola da ricordare: le chiavi che un cliente non ha toccato seguono la base; le chiavi che un cliente ha cambiato restano sue finché l’override non viene eliminato, dopodiché il tenant eredita di nuovo la base. Gli override che si perdono un miglioramento della base sono il rischio principale di questo schema: quando il testo sorgente della base cambia, le traduzioni sovrascritte di un tenant vengono contrassegnate come da rivedere (a meno che la modifica non sia stata ritradotta, come in questa esecuzione), ma un override nella lingua sorgente non riceve alcun segnale. L’editor del progetto base ha una risposta diretta a "chi è coinvolto": selezionate una chiave e una lingua, e check tenants elenca, tra i tenant che potete aprire, quelli che la sovrascrivono, con i loro valori.

Passo 5: caricare il cliente giusto

I file pubblicati di ogni tenant sulla CDN uniscono già la base con gli override del cliente: il file inglese di Physio North dice "Clients" e "Physio North", quello di Smile Dental dice "Patients" e "Smile Dental". L’app deve solo sapere quale cliente serve, dal sottodominio, dal login o da un valore di configurazione, e passare al backend l’ID di progetto di quel tenant:

import i18next from 'i18next'
import LocizeBackend from 'i18next-locize-backend'

// one tenant project ID per customer; customers without own wording load the base
const TENANT_PROJECT_IDS = {
  'physio-north': '<physio north tenant project id>',
  'praxis-am-see': '<praxis am see tenant project id>',
  'smile-dental': '<smile dental tenant project id>'
}
const BASE_PROJECT_ID = '<base project id>'

i18next.use(LocizeBackend).init({
  fallbackLng: 'en',
  backend: {
    projectId: TENANT_PROJECT_IDS[customer] ?? BASE_PROJECT_ID,
    version: 'latest'
  }
})

Poiché i file vengono caricati a runtime, la modifica di un cliente va online senza un rilascio della vostra app; quanto velocemente la vedono gli utenti dipende dalla cache, di cui parla aggiornare le traduzioni senza un nuovo deploy. Se invece includete le traduzioni nel bundle, scaricate allo stesso modo i file di ogni tenant nella vostra build.

Costi e accesso

• Piani: i tenant vengono fatturati con il loro progetto base. Growth ne include 5, Professional 10, Professional Plus 20, Enterprise 50; altri si aggiungono a pacchetti (prezzi).
• Parole: contano solo i valori sovrascritti, quindi le 14 chiavi inglesi che Smile Dental eredita non vengono addebitate di nuovo.
• Ripartizione per tenant: il pannello dei tenant mostra agli admin una stima di quanto vale l’uso di ogni tenant alle vostre tariffe, per rifatturare i costi ai clienti.
• Accesso: i clienti possono lavorare nel proprio tenant senza vedersi a vicenda; i membri della vostra organizzazione raggiungono ogni tenant.

A cosa fare attenzione

• Gli override congelano una chiave per quel cliente. Quando migliorate un testo base, controllate i tenant che lo sovrascrivono; eliminare un override restituisce la chiave alla base.
• Sovrascrivete ogni lingua che un cliente usa. Un override solo in inglese lascia le altre lingue del tenant sul testo base, quindi un cliente potrebbe leggere 48 ore in inglese e 24 in tedesco. Anche le bozze prodotte da un override sono override: contano come parole e non seguono più la base.
• Decidete chi può sovrascrivere cosa. Un cliente che modifica il proprio tenant può cambiare qualsiasi chiave, testi legali compresi. Tenete le formulazioni di compliance nella base e concordate con i clienti quali chiavi sono loro.
• Lingue per cliente. Con "can’t deviate from parent" disattivato, un tenant può avere lingue che la base non ha, e le lingue aggiunte alla base allora non gli vengono aggiunte automaticamente. Scegliete tenant per tenant.
• Prodotti diversi non sono tenant. Se le app di due clienti condividono poco più di una schermata di login, progetti separati sono più semplici.

Provatelo

La documentazione multi-tenant copre impostazioni e opzioni. Ogni account parte con una prova di 14 giorni con tutte le funzionalità e senza carta di credito, abbastanza per creare un progetto base e due tenant, sovrascrivere qualche chiave e caricare nella vostra app i file di ogni cliente.

Domande frequenti