Migrate from i18next

Most teams come from i18next or react-i18next with JSON locale files in the repo.

Mental model

i18next	StringPush
i18n.t('key')	t('key') after init()
useTranslation()	useTranslation() from @stringpush/react
namespaces	Flat keys: namespace.key in one bundle
i18n.changeLanguage()	setLocale('fr')
locales/en.json in repo	Published CDN bundles

1. Export existing strings

Collect your JSON locale files. Flatten nested objects if needed:

{
  "common": {
    "greeting": "Hello"
  }
}

→ key common.greeting, value Hello.

2. Import into StringPush

For each key/locale:

1. Admin → Keys → create key with default message.
2. Set translated values per locale.
3. Publish staging.

Bulk JSON import API is on the roadmap — for large catalogs, script against the admin API or ask support.

3. Replace initialization

Before (react-i18next):

import { useTranslation } from "react-i18next";

const { t } = useTranslation();
return <p>{t("common:greeting")}</p>;

After:

import { TranslationProvider, useTranslation } from "@stringpush/react";

// Wrap app with TranslationProvider — see /integration/react
const { t } = useTranslation();
return <p>{t("common.greeting")}</p>;

Note: StringPush uses dot keys (common.greeting), not colon namespaces.

4. Pass ICU values the same way

t("common.welcome", { name: user.name });
t("items.count", { count: items.length });

See ICU interpolation.

5. Remove locale JSON from the bundle

Delete public/locales/** from your repo once staging verifies. Keep a one-time export backup.

6. Codemod (coming soon)

Automated transforms for import swaps and simple t() calls will ship in a future release.

Until then, use find-and-replace for:

• react-i18next → @stringpush/react
• Namespace prefixes in keys (common:key → common.key)

Parallel run

1. Ship StringPush on staging environment first.
2. Keep i18next as fallback behind a feature flag if needed.
3. Switch production when all keys match.

Related

• Getting started
• React integration