Migrer depuis i18next

Déjà en production avec i18next ? @sonenta/react-i18next est un remplacement direct (drop-in) de react-i18next, même API useTranslation() et t() : vous changez simplement le provider et vos traductions viennent du CDN. Amenez vos fichiers locales/ existants dans Sonenta en une seule commande, puis gardez votre code tel quel. L'import crée les clés manquantes, met à jour chaque traduction, et est totalement idempotent : vous pouvez le relancer depuis la CI sans crainte. Voici le chemin complet : installer, importer, publier, vérifier, brancher le SDK.

Avant de commencer

Trois choses, et vous êtes prêt à importer :

• Un projet. Créez-en un dans le dashboard et copiez son project_uuid.
• Une clé API au scope mcp:*. La CLI passe par la surface MCP, une clé limitée au projet renvoie 403. La référence CLI explique comment en générer une.
• Node 18+ et vos fichiers i18next existants, disposés en <lang>/<namespace>.json (les dispositions atypiques sont gérées aussi).

1. Installer et initialiser

Installez la CLI globalement, générez une config pointant vers votre projet, et exportez votre clé.

# one global install: gives you the `sonenta` command (Node >= 18)
npm i -g @sonenta/cli

# scaffold sonenta.config.json and point it at your project
sonenta init --project <project_uuid>

# the CLI talks to the MCP surface, use an mcp:* scoped key
export SONENTA_TOKEN=snt_live_<prefix>.<secret>

sonenta init écrit un sonenta.config.json que vous pouvez committer. En CI, sautez init et passez --project plus la variable d'environnement SONENTA_TOKEN.

2. Prévisualiser, puis importer

L'import lit le chemin de chaque fichier pour en déduire la langue et le namespace : un arbre locales/ conventionnel ne nécessite aucune option. Faites un dry-run d'abord pour voir le plan, puis retirez --dry-run pour l'appliquer.

# the importer infers (language, namespace) from each path:
#   <lang>/<namespace>.json
locales/
├─ en/
│  ├─ common.json     → language en · namespace common
│  └─ checkout.json   → language en · namespace checkout
└─ fr/
   ├─ common.json     → language fr · namespace common
   └─ checkout.json   → language fr · namespace checkout

# preview first: no writes, prints exactly what WOULD change
sonenta import "./locales/**/*.json" --dry-run

# the real run: idempotent, safe to repeat
sonenta import "./locales/**/*.json"

✓ common · checkout   (en, fr)
  keys           312 created · 0 reused
  translations   624 created · 0 updated · 0 unchanged
  errors 0 · glossary 0 violations

# non-standard layout? override the inference per file:
sonenta import strings.fr.json --language fr --namespace common

Les arbres peuvent être imbriqués ou plats, les deux s'importent à l'identique. --status fixe le statut entrant (draft ou translated, défaut translated) ; --version cible une version non par défaut. Les pluriels exprimés en dictionnaire CLDR ({ one, other }) sont stockés en formes plurielles automatiquement.

3. Publier sur le CDN

L'import remplit le projet ; la publication le rend servable. Coupez une release et les bundles se propagent sur le CDN mondial que lit le SDK.

# cut a CDN release so the SDK and your build can fetch it
sonenta releases publish

→ released "main" · propagating to cdn.sonenta.com

Les releases sont des instantanés immuables d'une version. Re-publiez dès que vous importez du nouveau contenu, le SDK comme votre build statique récupèrent la dernière release.

4. Vérifier le bundle

Confirmez que le contenu est en ligne. Un bundle publié est un simple fichier JSON public par langue et namespace, récupérez-en un directement, ou ouvrez le projet dans le dashboard.

# the published bundle is public: no auth needed
curl -s https://cdn.sonenta.com/p/<project_uuid>/main/latest/fr/common.json

Note

Un 404 sur une langue ? Elle ne fait pas encore partie des langues du projet, ou la release ne s'est pas propagée, patientez quelques secondes et réessayez.

5. Brancher votre SDK sur Sonenta

Remplacez votre backend i18next par le provider Sonenta. Vos appels t(), vos clés et vos namespaces restent identiques, les traductions viennent maintenant du bundle CDN que vous venez de publier.

// src/main.tsx: point @sonenta/react-i18next at the same project
import { SonentaProvider } from "@sonenta/react-i18next";

<SonentaProvider
  projectUuid="<project_uuid>"
  token={import.meta.env.VITE_SONENTA_TOKEN}
  defaultLocale="fr"
  namespaces={["common", "checkout"]}
>
  <App />
</SonentaProvider>

Astuce

Des clés qui contiennent des points (une version, un prix, une référence biblique) ? Mettez keySeparator={false} et passez le projet en flat, voir le guide Clés plates ou imbriquées. Sinon, le défaut imbriqué fonctionne tel quel.

Ré-exécutable à tout moment

sonenta import est idempotent : ré-importer un contenu identique ne change rien (0 créées, 0 mises à jour, N inchangées). Branchez-le dans la CI pour garder Sonenta synchronisé avec votre dépôt, il ne crée que ce qui manque et ne met à jour que ce qui a réellement changé.

Ce que l'import gère

• Imbriqué ou plat. Les deux formes JSON s'importent vers les mêmes clés, aucun pré-traitement.
• Pluriels. Les dictionnaires de pluriels CLDR ({ one, other, … }, avec other obligatoire) deviennent des clés plurielles automatiquement.
• Résilience par fichier. Une langue ou un namespace inconnu est signalé comme erreur par unité, le reste de l'import aboutit quand même.
• Contrôles de glossaire. Les traductions importées passent par votre glossaire ; les violations sont listées, et ignorées en application stricte.
• Nettoyage des clés manquantes. Les événements de clé manquante ouverts pour les clés importées se résolvent dès l'arrivée des valeurs.

Ensuite

• CLI: Référence. Toutes les commandes, options et la clé mcp:* requise.
• Clés plates ou imbriquées: Guide. Empêcher les clés à points de casser après l'import.
• Mettre à jour la valeur source: Guide. Modifier le texte source d'une clé après coup.