Migrating from i18next to Intlayer

Why migrate from i18next to Intlayer?

Migration strategies

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

1. Compat adapter (recommended for existing apps) — Install @intlayer/i18next. This package exposes the exact same API as i18next but delegates all translation work to Intlayer under the hood. You keep your existing i18next.t(), i18next.changeLanguage(), and createInstance() calls — the only change is the import path and initialization.

2. Full migration — Gradually replace i18next APIs with native Intlayer tools and co-locate content in .content.ts files.

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 i18next app running on Intlayer with zero code changes.

1. 1

   Install Dependencies

   Install the Intlayer core packages and the compat adapter:

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

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

   You can keep i18next installed — the compat adapter uses it as a devDependency / peerDependency for TypeScript types.

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

   Copy content

   Copy code

   Copy the code to the clipboard

   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 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

   Update Bundler Aliases (Optional)

   If you are using a bundler (Vite, Webpack, esbuild), you can inject a module alias so that import ... from 'i18next' automatically resolves to @intlayer/i18next. This removes the need to manually change any imports in your codebase.

   For Vite:

   vite.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

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

   i18nextVitePlugin() wraps vite-intlayer's intlayer() plugin and adds the i18next → @intlayer/i18next alias for you. Using the plain intlayer() plugin from vite-intlayer compiles dictionaries but does not add that alias — you would then rename imports to @intlayer/i18next manually (see the next step).

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

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)

   Optional

   If you prefer to make the dependency explicit in your source files, or if you aren't using a bundler plugin to alias imports, you can rename imports manually:

   Show all table content

   Show all table content

   Open the table in a modal to view all data content clearly

   Before	After
   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'

   These are drop-in replacements — no changes to call signatures, arguments, or return types are required.

2. 5

   Enable AI-Powered Translation Automation

   Optional

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

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   # 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

   Copy content

   Copy code

   Copy the code to the clipboard

   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 adapter is in place, the following 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 logic 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 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