Migrer un projet existant depuis i18next vers Sonenta

Disons-le d’emblée : i18next est un excellent outil. C’est une bibliothèque mature, fiable, qui a internationalisé d’innombrables applications. Si vous l’utilisez déjà, vous n’avez aucune raison d’en changer la mécanique — t(), les namespaces, l’interpolation, l’ICU fonctionnent très bien.

Ce que les équipes finissent par chercher, ce n’est pas un remplaçant à i18next : c’est la couche qui lui manque quand un projet grandit. C’est exactement le positionnement de Sonenta, et c’est pourquoi la migration ressemble moins à un remplacement qu’à une montée en gamme. Voyons pourquoi, et comment le faire sans tout casser.

Pourquoi envisager la migration

Les douleurs n’apparaissent pas le premier jour. Elles arrivent à l’échelle — plusieurs langues, plusieurs développeurs, plusieurs branches.

• Des fichiers JSON qui divergent. Vos traductions vivent dans des fichiers versionnés. À deux ou trois développeurs, les fr.json partent dans tous les sens : conflits de merge, clés ajoutées d’un côté et pas de l’autre, doublons.
• Pas de workflow de traduction. i18next consomme des traductions ; il ne vous dit pas qui les écrit ni comment elles sont relues. En pratique, ça finit en copier-coller dans un tableur, sans statut ni validation.
• Des clés manquantes en production. Une clé ajoutée mais jamais traduite s’affiche en anglais — ou pire, en clé brute — chez l’utilisateur. Sans visibilité centralisée, vous l’apprenez par un client.
• Aucune source unique de vérité. Le code, le tableur des traducteurs et le glossaire ne sont jamais tout à fait d’accord.

Aucun de ces points n’est un défaut d’i18next : ce sont les limites d’une bibliothèque là où il faudrait une plateforme. i18next fait son travail ; il ne prétend simplement pas faire celui-là.

Ce que Sonenta ajoute — sans remplacer i18next

Sonenta ne jette pas i18next : il se pose par-dessus. Le paquet @sonenta/react-i18next est un drop-in — la même API i18next que vous connaissez, avec une source de vérité et une distribution gérées pour vous.

Concrètement, Sonenta apporte la couche plateforme manquante :

• une source unique de vérité pour vos clés, hors des fichiers qui divergent ;
• une distribution par CDN (corrections sans redéploiement — voir Stratégies de déploiement) ;
• un workflow de traduction avec statuts, relecture et glossaire ;
• la visibilité des clés manquantes, remontées au lieu d’être découvertes en production.

Vous gardez i18next pour ce qu’il fait bien ; vous déléguez à Sonenta ce qu’une bibliothèque ne peut pas faire seule.

i18next seul vs i18next + Sonenta

Pour situer les deux clairement — sans opposer ce qui est complémentaire :

Besoin	i18next seul	i18next + Sonenta
Rendu des traductions (t())	✅	✅ (identique)
Pluriels ICU, interpolation	✅	✅ (identique)
Source unique de vérité	Fichiers versionnés	Plateforme centrale
Workflow traducteur + relecture	❌ (à bricoler)	✅
Distribution CDN sans redéploi.	❌	✅
Visibilité des clés manquantes	❌	✅
Glossaire / cohérence terme	❌	✅

i18next reste le moteur de rendu ; Sonenta devient la chaîne d’approvisionnement des traductions qui l’alimente.

Compatibilité : vos habitudes i18next restent

C’est le point qui rassure le plus une équipe. Côté code, rien ne change dans votre façon d’écrire :

import { useTranslation } from "@sonenta/react-i18next"; // au lieu de react-i18next
function Cart() {
  const { t } = useTranslation("checkout");
  return <button>{t("submit")}</button>; // identique
}

Les noms de vos clés sont conservés. Vos namespaces existants sont importés tels quels. L’interpolation et les pluriels ICU continuent de fonctionner à l’identique. La migration n’est pas une réécriture de vos composants — c’est un changement de provenance des traductions, pas de leur usage.

Migrer sans big-bang

La bonne migration est progressive, namespace par namespace, avec un filet de sécurité à chaque étape. Personne ne devrait basculer 30 000 clés un vendredi soir.

1. Importer vos namespaces existants

Premier pas, sans risque : on importe vos fichiers JSON actuels dans Sonenta. Vos clés et leurs valeurs deviennent la base de la source de vérité — rien n’est encore modifié côté application.

2. Cohabitation, un namespace à la fois

On bascule un seul namespace vers Sonenta (par exemple checkout), pendant que le reste continue de se charger comme avant. Vous validez en conditions réelles, sur un périmètre réduit, puis vous avancez au suivant. À aucun moment l’application n’est dans un état « tout ou rien ».

3. Le filet de sécurité : un snapshot embarqué

On garde une copie embarquée des traductions dans le build, en repli. Si le réseau manque ou si le CDN n’a pas encore répondu, l’application affiche le snapshot — exactement comme un i18next classique. Vous gagnez la fraîcheur du CDN sans perdre la robustesse du fichier local.

4. Basculer la source de vérité

Une fois tous les namespaces migrés et validés, Sonenta devient la source de vérité. Vos fichiers JSON ne sont plus la référence : ils ne servent plus que de snapshot de secours, régénéré à chaque release.

Ce qui ne change pas pour les développeurs

Pour rassurer l’équipe, listons ce qui reste identique :

• l’API t(), useTranslation, les composants <Trans> ;
• les noms de clés, les namespaces, l’ICU, l’interpolation ;
• le build et le déploiement de votre application ;
• le fonctionnement hors-ligne, grâce au snapshot embarqué.

Ce qui change, en revanche : les traductions ne se corrigent plus dans un fichier puis un redéploiement, mais dans une plateforme qui les distribue. Les clés manquantes remontent au lieu de se cacher. Et les traducteurs travaillent dans un vrai workflow plutôt qu’un tableur.

Honnête sur l’effort

Migrer demande un investissement réel — soyons clairs plutôt que commerciaux. Pour une application typique, l’essentiel tient en quelques étapes : brancher le SDK, importer les namespaces, valider la cohabitation sur un périmètre, puis généraliser. Comptez une à deux journées d’ingénierie pour un projet de taille moyenne, davantage si vos fichiers sont très volumineux ou désordonnés (auquel cas le nettoyage que la migration impose est, en soi, bénéfique).

Le risque est faible parce que l’approche est réversible à chaque étape : tant que le snapshot embarqué existe, vous pouvez revenir en arrière sans casse.

Questions fréquentes

Faut-il réécrire nos composants ? Non. L’import change (@sonenta/react-i18next au lieu de react-i18next), mais t(), useTranslation et <Trans> restent identiques. Vos clés gardent leurs noms.

Que se passe-t-il si le CDN est injoignable ? Le snapshot embarqué prend le relais — exactement comme un i18next classique. Le réseau est une optimisation de fraîcheur, pas une dépendance bloquante.

Peut-on revenir en arrière ? Oui, à chaque étape. Tant que le snapshot embarqué existe et que la cohabitation est partielle, repointer un namespace sur vos fichiers d’origine est immédiat. La migration progressive est conçue pour être réversible.

Migrer, sans le grand soir

Migrer depuis i18next, ce n’est pas remplacer un outil qui marche — c’est lui ajouter la plateforme qui lui manquait à l’échelle : source de vérité, distribution CDN, workflow de traduction, visibilité des manques. Le tout en gardant l’API que vos développeurs connaissent déjà, progressivement, avec un filet de sécurité à chaque étape.

Reste une question légitime : est-ce que ça vaut le coup pour votre projet ? La réponse dépend de votre échelle et de votre rythme de changement — c’est exactement le calcul que pose le vrai coût de l’i18n.