Guida · Migrazione
Migrare da i18next
Già in produzione con i18next? @sonenta/react-i18next è un sostituto diretto (drop-in) di react-i18next — stessa API useTranslation() e t(): basta cambiare il provider e le vostre traduzioni arrivano in tempo reale dal CDN. Portate i vostri file locales/ esistenti in Sonenta con un solo comando, poi lasciate il vostro codice così com'è. L'import crea le chiavi mancanti, aggiorna ogni traduzione ed è completamente idempotente: potete rilanciarlo dalla CI senza timori. Ecco l'intero percorso: installare, importare, pubblicare, verificare, collegare l'SDK.
Prima di iniziare
Tre cose, e siete pronti a importare:
- Un progetto. Createne uno nella dashboard e copiatene il
project_uuid. - Una chiave API con scope
mcp:*. La CLI passa attraverso la superficie MCP — una chiave limitata al progetto restituisce403. La referenza CLI spiega come generarne una. - Node 18+ e i vostri file i18next esistenti, disposti come
<lang>/<namespace>.json(anche le disposizioni atipiche sono gestite).
1. Installare e inizializzare
Installate la CLI globalmente, generate una config che punta al vostro progetto ed esportate la vostra chiave.
terminal 1# one global install — gives you the `sonenta` command (Node >= 18)2npm i -g @sonenta/cli 4# scaffold sonenta.config.json and point it at your project5sonenta init --project <project_uuid> 7# the CLI talks to the MCP surface — use an mcp:* scoped key8export SONENTA_TOKEN=snt_live_<prefix>.<secret>sonenta init scrive un sonenta.config.json che potete committare. In CI, saltate init e passate --project più la variabile d'ambiente SONENTA_TOKEN. sonenta e SONENTA_* sono canonici; il vecchio comando sonenta e le variabili SONENTA_* funzionano ancora durante la transizione.
2. Anteprima, poi import
L'import legge il percorso di ogni file per dedurne lingua e namespace: un albero locales/ convenzionale non richiede alcuna opzione. Fate prima un dry-run per vedere il piano, poi rimuovete --dry-run per applicarlo.
your repo 1# the importer infers (language, namespace) from each path:2# <lang>/<namespace>.json3locales/4├─ en/5│ ├─ common.json → language en · namespace common6│ └─ checkout.json → language en · namespace checkout7└─ fr/8 ├─ common.json → language fr · namespace common9 └─ checkout.json → language fr · namespace checkoutterminal 1# preview first — no writes, prints exactly what WOULD change2sonenta import "./locales/**/*.json" --dry-run 4# the real run — idempotent, safe to repeat5sonenta import "./locales/**/*.json" 7✓ common · checkout (en, fr)8 keys 312 created · 0 reused9 translations 624 created · 0 updated · 0 unchanged10 errors 0 · glossary 0 violations 12# non-standard layout? override the inference per file:13sonenta import strings.fr.json --language fr --namespace commonGli alberi possono essere annidati o piatti — entrambi si importano in modo identico. --status imposta lo stato in ingresso (draft o translated, predefinito translated); --version punta a una versione non predefinita. I plurali espressi come dizionario CLDR ({ one, other }) vengono memorizzati automaticamente come forme plurali.
3. Pubblicare sul CDN
L'import riempie il progetto; la pubblicazione lo rende servibile. Tagliate una release e i bundle si propagano sul CDN globale da cui legge l'SDK.
terminal 1# cut a CDN release so the SDK and your build can fetch it2sonenta releases publish 4→ released "main" · propagating to cdn.sonenta.comLe release sono istantanee immutabili di una versione. Ripubblicate ogni volta che importate nuovi contenuti — sia l'SDK sia la vostra build statica recuperano l'ultima release.
4. Verificare il bundle
Confermate che il contenuto è online. Un bundle pubblicato è un semplice file JSON pubblico per lingua e namespace — recuperatene uno direttamente, oppure aprite il progetto nella dashboard.
terminal 1# the published bundle is public — no auth needed2curl -s https://cdn.sonenta.com/p/<project_uuid>/main/latest/fr/common.jsonUn 404 su una lingua? Non fa ancora parte delle lingue del progetto, oppure la release non si è propagata — attendete qualche secondo e riprovate.
5. Puntare il vostro SDK su Sonenta
Sostituite il vostro backend i18next con il provider Sonenta. Le vostre chiamate t(), le chiavi e i namespace restano identici — le traduzioni ora provengono dal bundle CDN che avete appena pubblicato.
main.tsx 1// src/main.tsx — point @sonenta/react-i18next at the same project2import { SonentaProvider } from "@sonenta/react-i18next"; 4<SonentaProvider5 projectUuid="<project_uuid>"6 token={import.meta.env.VITE_SONENTA_TOKEN}7 defaultLocale="fr"8 namespaces={["common", "checkout"]}9>10 <App />11</SonentaProvider>Chiavi che contengono punti (una versione, un prezzo, un riferimento biblico)? Impostate keySeparator={false} e passate il progetto a flat — vedi la guida Chiavi piatte o annidate. Altrimenti il valore predefinito annidato funziona così com'è.
Rilanciabile in qualsiasi momento
sonenta import è idempotente: reimportare contenuti identici non cambia nulla (0 create, 0 aggiornate, N invariate). Collegatelo alla CI per mantenere Sonenta sincronizzato con il vostro repository — crea solo ciò che manca e aggiorna solo ciò che è realmente cambiato.
Cosa gestisce l'import
- Annidato o piatto. Entrambe le forme JSON si importano verso le stesse chiavi — nessuna pre-elaborazione.
- Plurali. I dizionari di plurali CLDR (
{ one, other, … }, conotherobbligatorio) diventano automaticamente chiavi plurali. - Resilienza per file. Una lingua o un namespace sconosciuto viene segnalato come errore per unità — il resto dell'import va comunque a buon fine.
- Controlli del glossario. Le traduzioni importate passano attraverso il vostro glossario; le violazioni vengono elencate e saltate in caso di applicazione rigorosa.
- Pulizia delle chiavi mancanti. Gli eventi di chiave mancante aperti per le chiavi importate si risolvono non appena arrivano i valori.