Migrating from react-i18next / i18next to Intlayer

Why migrate from react-i18next / i18next to Intlayer?

Migration strategies

There are two complementary strategies for migrating from react-i18next / i18next to Intlayer:

1. Compat adapter (recommended for existing apps) — Install @intlayer/react-i18next (for React components) and/or @intlayer/i18next (for the core i18n instance). These packages expose the exact same API as react-i18next / i18next but delegate all translation work to Intlayer under the hood. You keep your existing useTranslation, Trans, withTranslation, i18next.t() calls — the only change is the import path.

2. Full migration — Gradually replace react-i18next APIs with native Intlayer hooks (useIntlayer, IntlayerProvider) and co-locate content in .content.ts files alongside your components.

This guide covers Strategy 1 first (drop-in compat adapter), then walks through the optional full migration.

Table of Contents

Quick migration

The following steps are the minimum required to get your existing react-i18next app running on Intlayer with zero code changes.

1. 1

   Install Dependencies

   Install the Intlayer core packages and the compat adapters:

   bash

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   npm install intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-pluginnpx intlayer init

   You can keep react-i18next and i18next installed — the compat adapters use them as devDependencies / optional peerDependencies for TypeScript types. You don't need to change any package.json peers.

2. 2

   Configure Intlayer

   The intlayer init command creates a starter intlayer.config.ts. Update it to match your existing locales and point the syncJSON plugin at your message files:

   intlayer.config.ts

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Add all your existing locales here
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // matches react-i18next placeholder syntax: {{name}}
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   export default config;

   source maps a locale to its JSON file path. location tells the Intlayer watcher which folder to monitor for changes. The format: 'i18next' option ensures that placeholders like {{name}} are parsed correctly.

3. 3

   Add the Intlayer Plugin to your Bundler

   Wrap your existing bundler config with the compat plugin. It composes the core Intlayer plugin, wires up content watching, and — critically — injects module aliases so that your existing import … from 'react-i18next' (and 'i18next') calls are transparently redirected to @intlayer/react-i18next / @intlayer/i18next at build time. No source file changes are needed.

   For Vite:

   vite.config.ts

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   import { defineConfig } from "vite";
   import react from "@vitejs/plugin-react";
   import { reactI18nextVitePlugin } from "@intlayer/react-i18next/plugin";
   
   export default defineConfig({
     plugins: [react(), reactI18nextVitePlugin()],
   });

   reactI18nextVitePlugin() wraps vite-intlayer's intlayer() plugin and adds the react-i18next / i18next aliases. Using the plain intlayer() plugin from vite-intlayer compiles dictionaries but does not add those aliases — you would then rename imports to @intlayer/* manually (see Step 4).

   For Next.js:

   If you are using next-i18next (Pages Router integration), install @intlayer/next-i18next and next-intlayer:

   bash

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   npm install @intlayer/next-i18next next-intlayer

   Then add the compat plugin to your next.config.ts (it injects the next-i18next / react-i18next / i18next aliases):

   next.config.ts

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   import type { NextConfig } from "next";
   import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
   
   const withIntlayer = createNextI18nPlugin();
   
   const nextConfig: NextConfig = {
     /* your options */
   };
   
   export default withIntlayer(nextConfig);

   You no longer need i18next.init() or manual provider bootstrapping. Intlayer compiles all dictionaries at build time, so there is no runtime loading step. The aliased provider handles initialization for you.

That's it for the quick migration. Your app now runs on Intlayer while keeping every react-i18next import and API intact.

Typed translation keys — automatic. Once Intlayer compiles your dictionaries, useTranslation and getFixedT are typed against your actual content. Keys are autocompleted in your IDE and invalid paths cause TypeScript errors at build time — no extra setup required.

tsx

Копіювати вміст

Копіювати код

Скопіюйте код у буфер обміну

// 'about' is a registered dictionary key → t() only accepts valid dot-pathsconst { t } = useTranslation("about");t("counter.label"); // ✓ autocompletedt("does.not.exist"); // ✗ TypeScript error// Server-side (i18next instance)const tAbout = i18n.getFixedT(null, "about");tAbout("counter.label"); // ✓ typed

Complete migration

The steps below are optional and can be done incrementally. They unlock the full Intlayer feature set: visual editor, CMS, typed content files, AI-powered translation, and more.

1. 4

   Explicit import renaming (optional)

   Необов'язково

   The Intlayer plugins already handle aliasing at the bundler level. If you prefer to make the dependency explicit in your source files, you can rename imports manually:

   Показати весь вміст таблиці

   Показати весь вміст таблиці

   Відкрийте таблицю в модальному вікні, щоб чітко переглянути всі дані

   Before	After
   import { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-i18next'
   import { Trans } from 'react-i18next'	import { Trans } from '@intlayer/react-i18next'
   import { withTranslation } from 'react-i18next'	import { withTranslation } from '@intlayer/react-i18next'
   import { I18nextProvider } from 'react-i18next'	import { I18nextProvider } from '@intlayer/react-i18next'
   import { initReactI18next } from 'react-i18next'	import { initReactI18next } from '@intlayer/react-i18next'
   import i18next from 'i18next'	import i18next from '@intlayer/i18next'
   import { createInstance } from 'i18next'	import { createInstance } from '@intlayer/i18next'
   import { t } from 'i18next'	import { t } from '@intlayer/i18next'

   For Next.js (next-i18next):

   Показати весь вміст таблиці

   Показати весь вміст таблиці

   Відкрийте таблицю в модальному вікні, щоб чітко переглянути всі дані

   Before	After
   import { serverSideTranslations } from 'next-i18next/serverSideTranslations'	import { serverSideTranslations } from '@intlayer/next-i18next'
   import { appWithTranslation } from 'next-i18next'	import { appWithTranslation } from '@intlayer/next-i18next'
   import { useTranslation } from 'next-i18next'	import { useTranslation } from '@intlayer/next-i18next'

2. 5

   Enable AI-Powered Translation Automation

   Необов'язково

   Once Intlayer is wired up, use its CLI to fill missing translations automatically:

   bash

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   # Test for missing translations (add to CI)npx intlayer test# Fill missing translations with AInpx intlayer fill

   Add the AI configuration to intlayer.config.ts:

   intlayer.config.ts

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // default
       // model: "gpt-4o-mini",   // default
     },
   };
   
   export default config;

   See Intlayer CLI documentation for all available options.

What you can delete after migration

Once the compat adapters are in place, the following react-i18next / i18next boilerplate can be removed:

When you are ready to go further, Intlayer automatically discovers all .content.ts and .content.json files anywhere in your codebase (by default, anywhere inside ./src). You can place a my-component.content.ts file right next to your MyComponent.tsx and Intlayer will pick it up at build time with no additional configuration — no imports, no registration, no centralized index file needed. This makes co-locating translations with pages and components completely frictionless.

Configure TypeScript

Intlayer uses module augmentation to provide full TypeScript intellisense for your translation keys. Make sure your tsconfig.json includes the auto-generated types:

{  // ... Your existing TypeScript configurations  "include": [    // ... Your existing TypeScript configurations    ".intlayer/**/*.ts", // Include the auto-generated types  ],}

Git Configuration

Add Intlayer's generated directory to your .gitignore:

# Ignore the files generated by Intlayer.intlayer

Go Further

• Visual Editor — Manage translations visually in your browser: Intlayer Visual Editor
• CMS — Externalize and manage content remotely: Intlayer CMS
• VS Code Extension — Get autocompletion and real-time translation error detection: Intlayer VS Code Extension
• CLI Reference — Full list of CLI commands: Intlayer CLI
• Intlayer with React — Full setup guide for React: intlayerwithvite+react.md
• Intlayer with Next.js — Full setup guide for Next.js: intlayerwithnextjs_16.md