Migrating from next-i18next to Intlayer

Why migrate from next-i18next to Intlayer?

Migration strategies

Since next-i18next wraps react-i18next and i18next under the hood, there are two complementary strategies for migrating to Intlayer:

1. Compat adapter (recommended for existing apps) — Install @intlayer/next-i18next, @intlayer/react-i18next, and @intlayer/i18next. These packages expose the exact same API as their counterparts but delegate all translation work to Intlayer under the hood. You keep your existing useTranslation, appWithTranslation, serverSideTranslations calls, and Next.js Pages routing unchanged — the only change is the initialization.

2. Full migration — Gradually replace next-i18next APIs with native Intlayer hooks (useIntlayer) 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 Next.js Pages Router app running on Intlayer with zero code changes in your pages and components.

1. 1

   Install Dependencies

   Install the Intlayer core packages and the compat adapters:

   bash

   Salin konten

   Salin kode

   Salin kode ke clipboard

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

   You can safely keep next-i18next, react-i18next, and i18next installed during migration, though you will remove them once aliased.

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 next-i18next message files (usually inside public/locales):

   intlayer.config.ts

   Salin konten

   Salin kode

   Salin kode ke 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: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/locales",
       }),
     ],
   };
   
   export default config;

   source maps a locale and a namespace (key) to its JSON file path. location tells the Intlayer watcher which folder to monitor for changes. The format: 'i18next' option ensures that placeholders are parsed correctly for next-i18next.

3. 3

   Update Next.js Configuration

   Wrap your existing next.config.ts (or .js) with createNextI18nPlugin from @intlayer/next-i18next/plugin. This wrapper composes withIntlayer and injects the next-i18next / react-i18next / i18next → @intlayer/* aliases, so your existing import { useTranslation } from 'next-i18next' calls are transparently redirected at build time. No source file changes are needed.

   next.config.ts

   Salin konten

   Salin kode

   Salin kode ke clipboard

   import type { NextConfig } from "next";
   import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
   // You can remove the i18n configuration imported from next-i18next.config.js
   // import { i18n } from './next-i18next.config';
   
   const withIntlayer = createNextI18nPlugin();
   
   const nextConfig: NextConfig = {
     // Intlayer manages the Next.js i18n routing under the hood,
     // so you don't need to pass the i18n object here anymore.
   };
   
   export default withIntlayer(nextConfig);

   You no longer need next-i18next.config.js. Intlayer compiles all dictionaries at build time, handling locale detection, routing, and dictionary loading seamlessly.

   Prefer the plain withIntlayer from next-intlayer/server? It compiles your dictionaries but does not add the next-i18next / react-i18next / i18next aliases — you would then rename imports to @intlayer/* manually (see Step 4).

That's it for the quick migration. Your Next.js app now runs on Intlayer while keeping every useTranslation, serverSideTranslations, and appWithTranslation call 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

Salin konten

Salin kode

Salin kode ke clipboard

// Pages Router — 'about' is a registered dictionary keyconst { t } = useTranslation("about");t("counter.label"); // ✓ autocompletedt("does.not.exist"); // ✗ TypeScript error// getStaticProps / getServerSideProps (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)

   Opsional

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

   Tampilkan semua isi tabel

   Tampilkan semua isi tabel

   Buka tabel dalam modal untuk melihat semua isi data dengan jelas

   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'
   import { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-i18next'

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

2. 5

   Enable AI-Powered Translation Automation

   Opsional

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

   bash

   Salin konten

   Salin kode

   Salin kode ke 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

   Salin konten

   Salin kode

   Salin kode ke 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: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
         location: "public/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 next-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 Next.js (Pages Router) — Full setup guide for Next.js: intlayerwithnextjspagerouter.md