Migrating from next-intl to Intlayer

Why migrate from next-intl to Intlayer?

Migration strategy

The recommended approach for existing apps is the compat adapter: install @intlayer/next-intl, which exposes the exact same API as next-intl but delegates all translation work to Intlayer under the hood.

You keep your existing useTranslations, getTranslations, NextIntlClientProvider and friends — the only change is the import path. No refactoring of call signatures, prop shapes, or component structure is required.

Over time you can optionally migrate individual files to Intlayer's richer .content.ts format to unlock the visual editor, CMS, and per-component content scoping — but that step is entirely optional and can be done incrementally.

Table of Contents

Quick migration

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

1. 1

   Install Dependencies

   Install the Intlayer core packages and the @intlayer/next-intl compat adapter:

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   npm install intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-pluginnpx intlayer init

   Keep next-intl installed — it is still required for URL routing (createNavigation, createMiddleware, Link, redirect, usePathname, useRouter). The compat adapter does not replace the routing layer.

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({
         // 'icu' matches next-intl's ICU placeholder syntax: {name}, {count, plural, ...}
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
   };
   
   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: 'icu' option ensures ICU placeholders like {name} and {count, plural, one {# item} other {# items}} are parsed correctly.

   For a complete list of configuration options, see the configuration documentation.

3. 3

   Add the Intlayer Plugin to Next.js

   Wrap your existing Next.js config with createNextIntlPlugin from @intlayer/next-intl/plugin. This wrapper composes withIntlayer and registers the next-intl → @intlayer/next-intl aliases for you:

   next.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

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

   createNextIntlPlugin() wraps withIntlayer, automatically detects Webpack or Turbopack, wires up content watching, dictionary compilation, and — critically — injects module aliases so that your existing import … from 'next-intl' calls are transparently redirected to @intlayer/next-intl at build time. The routing entry next-intl/routing is left pointing at the real package. No source file changes are needed.

   Prefer the plain withIntlayer from next-intlayer/server? It will compile your dictionaries, but it does not add the next-intl aliases — you would then have to rename imports to @intlayer/next-intl manually (see Step 4).

   You no longer need getRequestConfig or loadMessages. With next-intl, you had to write a src/i18n.ts file that loaded JSON message bundles on every request via getRequestConfig. Intlayer compiles all dictionaries at build time, so there is no runtime loading step. You can delete that file entirely (or keep only the routing parts if you still use createNavigation).

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

Typed translation keys — automatic. Once Intlayer compiles your dictionaries, useTranslations and getTranslations 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

Copy content

Copy code

Copy the code to the clipboard

// Client component — 'about' is a registered dictionary keyconst t = useTranslations("about");t("counter.label"); // ✓ autocompletedt("does.not.exist"); // ✗ TypeScript error// Server componentconst t = await getTranslations("about");t("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)

   Optional

   The createNextIntlPlugin() wrapper already handles next-intl → @intlayer/next-intl aliasing at the bundler level. If you prefer to make the dependency explicit in your source files (and use the plain withIntlayer plugin instead), 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 { useTranslations } from 'next-intl'	import { useTranslations } from '@intlayer/next-intl'
   import { useLocale } from 'next-intl'	import { useLocale } from '@intlayer/next-intl'
   import { NextIntlClientProvider } from 'next-intl'	import { NextIntlClientProvider } from '@intlayer/next-intl'
   import { getTranslations } from 'next-intl/server'	import { getTranslations } from '@intlayer/next-intl/server'
   import { getLocale } from 'next-intl/server'	import { getLocale } from '@intlayer/next-intl/server'
   import { setLocale } from 'next-intl/server'	import { setLocale } from '@intlayer/next-intl/server'
   import { getMessages } from 'next-intl/server'	import { getMessages } from '@intlayer/next-intl/server'

   Always keep routing imports from the real next-intl — the compat adapter does not replace the URL routing layer:

   ts

   Copy content

   Copy code

   Copy the code to the clipboard

   // ✅ Always keep these from the real 'next-intl'import { createNavigation } from "next-intl/routing";import { createMiddleware } from "next-intl/server";import { defineRouting } from "next-intl/routing";

   Alternatively, you can use defineRouting from @intlayer/next-intl/routing which merges locale config from your intlayer.config.ts automatically.

2. 5

   Enable AI-Powered Translation Automation

   Optional

   Once Intlayer is wired up, you can use its CLI to fill missing translations automatically using the LLM of your choice:

   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 an OPENAI_API_KEY (or your preferred provider key) to your .env file, then extend your 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: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
     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 @intlayer/next-intl is in place, the following next-intl 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 an about.content.ts file right next to your about/page.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 — Full setup guide for Next.js: intlayerwithnextjs_16.md