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.