Migrating an existing project from i18next to Sonenta

Let’s say it up front: i18next is an excellent tool. It’s a mature, reliable library that has internationalized countless applications. If you’re already on it, you have no reason to change its mechanics — t(), namespaces, interpolation and ICU all work just fine.

What teams eventually go looking for isn’t a replacement for i18next: it’s the layer it’s missing once a project grows. That’s exactly where Sonenta sits, which is why the move feels less like a replacement than an upgrade. Here’s why, and how to do it without breaking things.

Why consider migrating

The pain doesn’t show up on day one. It arrives at scale — several languages, several developers, several branches.

• Diverging JSON files. Your translations live in versioned files. With two or three developers, the en.json files drift apart: merge conflicts, keys added on one side and not the other, duplicates.
• No translation workflow. i18next consumes translations; it doesn’t tell you who writes them or how they get reviewed. In practice it ends up as copy-paste in a spreadsheet, with no status and no sign-off.
• Missing keys in production. A key that’s added but never translated shows up in English — or worse, as a raw key — to the user. With no central visibility, you hear about it from a customer.
• No single source of truth. The code, the translators’ spreadsheet and the glossary never quite agree.

None of this is a flaw in i18next: these are the limits of a library where you need a platform. i18next does its job; it just doesn’t claim to do that one.

What Sonenta adds — without replacing i18next

Sonenta doesn’t throw i18next out: it sits on top. The @sonenta/react-i18next package is a drop-in — the same i18next API you know, with a source of truth and distribution managed for you.

Concretely, Sonenta adds the missing platform layer:

• a single source of truth for your keys, out of the files that drift;
• CDN distribution (fixes without a redeploy — see deployment strategies);
• a translation workflow with statuses, review and a glossary;
• visibility into missing keys, surfaced instead of discovered in production.

You keep i18next for what it does well; you hand Sonenta what a library can’t do alone.

i18next alone vs i18next + Sonenta

To place the two clearly — without pitting complements against each other:

Need	i18next alone	i18next + Sonenta
Rendering translations (t())	✅	✅ (identical)
ICU plurals, interpolation	✅	✅ (identical)
Single source of truth	Versioned files	Central platform
Translator workflow + review	❌ (roll your own)	✅
CDN distribution, no redeploy	❌	✅
Missing-key visibility	❌	✅
Glossary / term consistency	❌	✅

i18next stays the rendering engine; Sonenta becomes the translation supply chain that feeds it.

Compatibility: your i18next habits stay

This is the part that reassures a team most. In the code, nothing changes about how you write:

import { useTranslation } from "@sonenta/react-i18next"; // instead of react-i18next
function Cart() {
  const { t } = useTranslation("checkout");
  return <button>{t("submit")}</button>; // identical
}

Your key names are kept. Your existing namespaces are imported as-is. Interpolation and ICU plurals keep working exactly the same. Migrating isn’t a rewrite of your components — it’s a change in where translations come from, not how they’re used.

Migrating without a big-bang

A good migration is gradual, namespace by namespace, with a safety net at every step. Nobody should flip 30,000 keys on a Friday night.

1. Import your existing namespaces

First, risk-free step: import your current JSON files into Sonenta. Your keys and their values become the basis of the source of truth — nothing changes on the app side yet.

2. Cohabitation, one namespace at a time

You switch a single namespace to Sonenta (say checkout) while the rest keeps loading as before. You validate in real conditions, on a small surface, then move to the next. At no point is the app in an all-or-nothing state.

3. The safety net: a bundled snapshot

You keep an embedded copy of the translations in the build, as a fallback. If the network is down or the CDN hasn’t answered yet, the app shows the snapshot — exactly like classic i18next. You gain the freshness of the CDN without losing the robustness of the local file.

4. Flip the source of truth

Once every namespace is migrated and validated, Sonenta becomes the source of truth. Your JSON files are no longer the reference: they’re just a fallback snapshot, regenerated on each release.

What doesn’t change for developers

To reassure the team, here’s what stays identical:

• the t() API, useTranslation, the <Trans> component;
• key names, namespaces, ICU, interpolation;
• your app’s build and deploy;
• offline behavior, thanks to the bundled snapshot.

What does change: translations are no longer fixed in a file and redeployed, but in a platform that distributes them. Missing keys surface instead of hiding. And translators work in a real workflow rather than a spreadsheet.

Honest about the effort

Migrating takes real investment — let’s be clear rather than salesy. For a typical app, the gist is a few steps: wire in the SDK, import the namespaces, validate cohabitation on a small scope, then generalize. Budget one to two engineering days for a medium-sized project, more if your files are very large or messy (in which case the cleanup the migration forces is, in itself, a win).

The risk is low because the approach is reversible at every step: as long as the bundled snapshot exists, you can roll back without breakage.

FAQ

Do we have to rewrite our components? No. The import changes (@sonenta/react-i18next instead of react-i18next), but t(), useTranslation and <Trans> stay identical. Your keys keep their names.

What if the CDN is unreachable? The bundled snapshot takes over — exactly like classic i18next. The network is a freshness optimization, not a blocking dependency.

Can we roll back? Yes, at every step. As long as the bundled snapshot exists and cohabitation is partial, pointing a namespace back at your original files is immediate. The gradual migration is designed to be reversible.

Migrating, without the grand reveal

Migrating from i18next isn’t replacing a tool that works — it’s adding the platform it was missing at scale: source of truth, CDN distribution, translation workflow, visibility into gaps. All while keeping the API your developers already know, gradually, with a safety net at every step.

One fair question remains: is it worth it for your project? The answer comes down to your scale and your rate of change — exactly the math laid out in the real cost of i18n.