Migrer depuis i18next

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é.

1# one global install — gives you the `verbumia` command (Node >= 18)2npm i -g @verbumia/cli 4# scaffold verbumia.config.json and point it at your project5verbumia init --project <project_uuid> 7# the CLI talks to the MCP surface — use an mcp:* scoped key8export VERBUMIA_TOKEN=vrb_live_<prefix>.<secret>

verbumia init écrit un verbumia.config.json que vous pouvez committer. En CI, sautez init et passez --project plus la variable d'environnement VERBUMIA_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.

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 checkout

1# preview first — no writes, prints exactly what WOULD change2verbumia import "./locales/**/*.json" --dry-run 4# the real run — idempotent, safe to repeat5verbumia 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:13verbumia 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.

1# cut a CDN release so the SDK and your build can fetch it2verbumia releases publish 4→ released "main" · propagating to cdn.verbumia.ca

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.

1# the published bundle is public — no auth needed2curl -s https://cdn.verbumia.ca/p/<project_uuid>/main/latest/fr/common.json

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 Verbumia

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

1// src/main.tsx — point @verbumia/react-i18next at the same project2import { VerbumiaProvider } from "@verbumia/react-i18next"; 4<VerbumiaProvider5  projectId="<project_uuid>"6  apiKey={import.meta.env.VITE_VERBUMIA_KEY}7  defaultLocale="fr"8  namespaces={["common", "checkout"]}9>10  <App />11</VerbumiaProvider>

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.

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.