Locize
LoginRegister

Migrating from SimpleLocalize to Locize

This guide walks you through moving your translations from SimpleLocalize to Locize and switching your i18next configuration to use the native i18next-locize-backend plugin.

The migration preserves all your translation content. Your application code — the t() calls, namespaces, and language keys — does not change.

Before you start

You will need:

  • A Locize account (register here)
  • A new Locize project (create one after registering)
  • Your Locize Project ID and API Key (found in your project settings)
  • Access to your SimpleLocalize project to export translation files

Step 1 — Export your translations from SimpleLocalize

In SimpleLocalize, go to Downloads (or use the CLI):

# Using the SimpleLocalize CLI
simplelocalize download --apiKey YOUR_API_KEY --projectToken YOUR_TOKEN \
  --downloadFormat multi-language-json \
  --downloadPath ./translations/{{lng}}/{{ns}}.json

This produces JSON files organised by language and namespace, for example:

translations/
  en/
    common.json
    navigation.json
  de/
    common.json
    navigation.json
  fr/
    common.json
    navigation.json

If your SimpleLocalize project uses a flat single-file format (one file per language rather than per namespace), the same structure applies — you can import flat JSON files into Locize directly.

Step 2 — Create your project in Locize

  1. Log in to locize.app
  2. Create a new project — give it the same name as your SimpleLocalize project
  3. Add your languages (match the languages in your SimpleLocalize export)
  4. Note your Project ID from the project settings page

Step 3 — Import translations using the i18next-cli

The i18next-cli handles the migration in one command:

npx i18next-cli locize-migrate \
  --project-id YOUR_LOCIZE_PROJECT_ID \
  --api-key YOUR_LOCIZE_API_KEY \
  --path ./translations

This uploads all namespaces and languages to your Locize project. Keys and values are preserved exactly.

Alternatively, use the Locize web interface: go to your project, select a namespace, and use Import to upload each JSON file.

Step 4 — Install the Locize backend plugin

Remove the SimpleLocalize dependencies:

npm uninstall i18next-http-backend axios
# or
yarn remove i18next-http-backend axios

Install the Locize backend plugin:

npm install i18next-locize-backend
# or
yarn add i18next-locize-backend

Step 5 — Update your i18n configuration

Before (SimpleLocalize):

import i18n from 'i18next'
import Backend from 'i18next-http-backend'
import { initReactI18next } from 'react-i18next'

const cdnBaseUrl = 'https://cdn.simplelocalize.io'
const projectToken = 'YOUR_TOKEN'
const environment = '_latest'

i18n
  .use(Backend)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    backend: {
      loadPath: `${cdnBaseUrl}/${projectToken}/${environment}/{{lng}}/{{ns}}`
    }
  })

After (Locize):

import i18n from 'i18next'
import Backend from 'i18next-locize-backend'
import { initReactI18next } from 'react-i18next'

const isProduction = process.env.NODE_ENV === 'production'

const locizeOptions = {
  projectId: 'YOUR_LOCIZE_PROJECT_ID',
  apiKey: isProduction ? undefined : 'YOUR_LOCIZE_API_KEY', // never expose apiKey in production
}

i18n
  .use(Backend)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    saveMissing: !isProduction, // auto-capture new keys during development
    backend: locizeOptions
  })

The apiKey is only needed in development (for saveMissing). In production, translations are fetched from the public CDN using the projectId alone.

Step 6 — Replace saveMissing custom code (if applicable)

If you had a custom missingKeyHandler with interval-based batching in your SimpleLocalize setup, remove it entirely. The i18next-locize-backend implements the create function natively — saveMissing: true is all you need.

Remove this pattern:

// Remove this — no longer needed with i18next-locize-backend
const missing = []
const SYNC_INTERVAL = 30 * 1000
setInterval(async () => {
  if (missing.length > 0) {
    await createTranslationKeys({ translationKeys: missing })
    missing.length = 0
  }
}, SYNC_INTERVAL)

missingKeyHandler: async (languages, namespace, translationKey, fallbackValue) => {
  missing.push({ translationKey, language: languages[0], fallbackValue })
}

Step 7 — Verify

Start your application in development mode. Visit a page that uses translations — you should see them loading from the Locize CDN. Check your Locize project dashboard to confirm namespaces and keys are present.

To verify CDN delivery is working correctly, open your browser's network tab and confirm requests are going to https://api.locize.app or https://api.lite.locize.app (based on your CDN type).

Optional: Enable automatic translation on new keys

One of the advantages of the Locize + saveMissing setup is the ability to automatically AI-translate new keys as they arrive. In your Locize project settings, enable Automatic Translation and configure your preferred AI provider.

From that point on, any new key your developers add will be:

  1. Automatically sent to Locize (via saveMissing)
  2. Automatically translated into all configured target languages
  3. Immediately available via CDN — no manual step required

See the automatic translation docs for setup details.

Troubleshooting

Keys are not loading: Check that your projectId matches the Locize project, and that you added the correct languages in Locize.

Missing keys not appearing in Locize: Confirm saveMissing: true is set and that you are passing a valid apiKey in your development environment. The apiKey must have write access.

Namespace mismatch: If your SimpleLocalize project used flat files (no namespace path), import into the translation namespace in Locize (the i18next default).

Need help? Contact support@locize.com.