How to make multilingual (i18n) an existing Next.js application afterward (i18n guide 2026)

See Application Template on GitHub.

Table of Contents

Why is it hard to internationalize an existing application?

If you've ever tried to add multiple languages to an app that was built for just one, you know the pain. It's not just "hard", it's tedious. You have to comb through every single file, hunt down every string of text, and move them into separate dictionary files.

Then comes the risky part: replacing all that text with code hooks without breaking your layout or logic. It's the kind of work that halts new feature development for weeks and feels like endless refactoring.

What is the Intlayer Compiler?

The Intlayer Compiler was built to skip that manual grunt work. Instead of you manually extracting strings, the compiler does it for you. It scans your code, finds the text, and uses AI to generate the dictionaries behind the scenes. Then, it modifies your code during the build to inject the necessary i18n hooks. Basically, you keep writing your app as if it's single-language, and the compiler handles the multilingual transformation automatically.

Doc Compiler: /doc/compiler

Limitations

Because the compiler performs code analysis and transformation (inserting hooks and generating dictionaries) at compile time, it can slow down the build process of your application.

To mitigate this impact during development, you can configure the compiler to run in 'build-only' mode or disable it when not needed.

Step-by-Step Guide to Set Up Intlayer in a Next.js Application

1. 1

   Install Dependencies

   Install the necessary packages using npm:

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   npm install intlayer next-intlayernpm install @intlayer/babel --save-devnpx intlayer init

   • intlayer

     The core package that provides internationalization tools for configuration management, translation, content declaration, transpilation, and CLI commands.

   • next-intlayer

     The package that integrates Intlayer with Next.js. It provides context providers and hooks for Next.js internationalization. Additionally, it includes the Next.js plugin for integrating Intlayer with Webpack or Turbopack, as well as proxy for detecting the user's preferred locale, managing cookies, and handling URL redirection.

2. 2

   Configure Your Project

   Create a config file to configure the languages of your application:

   intlayer.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH],    defaultLocale: Locales.FRENCH,  },  routing: {    mode: "search-params",  },  compiler: {    /**     * Indicates if the compiler should be enabled.     */    enabled: true,    /**     * Output directory for the optimized dictionaries.     */    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,    /**     * Inset only content in generated file, without key.     */    noMetadata: false,    /**     * Dictionary key prefix     */    dictionaryKeyPrefix: "", // Remove base prefix    /**     * Indicates if the components should be saved after being transformed.     *     * - If `true`, the compiler will rewrite the component file in the disk. So the transformation will be permanent, and the compiler will skip the transformation for the next process. That way, the compiler can transform the app, and then it can be removed.     *     * - If `false`, the compiler will inject the `useIntlayer()` function call into the code in the build output only, and keep the base codebase intact. The transformation will be done only in memory.     */    saveComponents: false,  },  ai: {    provider: "openai",    model: "gpt-5-mini",    apiKey: process.env.OPEN_AI_API_KEY,    applicationContext: "This app is an map app",  },};export default config;

   Note: Ensure you have your OPEN_AI_API_KEY set in your environment variables.

   Through this configuration file, you can set up localized URLs, proxy redirection, cookie names, the location and extension of your content declarations, disable Intlayer logs in the console, and more. For a complete list of available parameters, refer to the configuration documentation.

3. 3

   Integrate Intlayer in Your Next.js Configuration

   Configure your Next.js setup to use Intlayer:

   next.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import type { NextConfig } from "next";import { withIntlayer } from "next-intlayer/server";const nextConfig: NextConfig = {  /* config options here */};export default withIntlayer(nextConfig);

   The withIntlayer() Next.js plugin is used to integrate Intlayer with Next.js. It ensures the building of content declaration files and monitors them in development mode. It defines Intlayer environment variables within the Webpack or Turbopack environments. Additionally, it provides aliases to optimize performance and ensures compatibility with server components.

4. 4

   Configure Babel

   The Intlayer compiler requires Babel to extract and optimize your content. Update your babel.config.js (or babel.config.json) to include the Intlayer plugins:

   babel.config.js

   Copy content

   Copy code

   Copy the code to the clipboard

   const {  intlayerExtractBabelPlugin,  intlayerOptimizeBabelPlugin,  getExtractPluginOptions,  getOptimizePluginOptions,} = require("@intlayer/babel");module.exports = {  presets: ["next/babel"],  plugins: [    [intlayerExtractBabelPlugin, getExtractPluginOptions()],    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],  ],};

5. 5

   Detect Locale in your pages

   Remove everything from RootLayout and replace it with the following code:

   src/app/layout.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import type { Metadata } from "next";import type { ReactNode } from "react";import "./globals.css";import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer";import { getHTMLTextDir, getIntlayer } from "intlayer";import { getLocale } from "next-intlayer/server";export { generateStaticParams } from "next-intlayer";export const generateMetadata = async (): Promise<Metadata> => {  const locale = await getLocale();  const { title, description, keywords } = getIntlayer("metadata", locale);  return {    title,    description,    keywords,  };};const RootLayout = async ({  children,}: Readonly<{  children: ReactNode;}>) => {  const locale = await getLocale();  return (    <html lang={locale} dir={getHTMLTextDir(locale)}>      <IntlayerClientProvider defaultLocale={locale}>        <body>{children}</body>      </IntlayerClientProvider>    </html>  );};export default RootLayout;

6. 6

   Compile your components

   With the compiler enabled, you no longer need to manually declare content dictionaries (like .content.ts files).

   Instead, you can write your content directly in your code as strings. Intlayer will analyze your code, generate the translations using the configured AI provider, and replace the strings with localized content at compile time.

   Just write your components with hardcoded strings in your default locale. The compiler handles the rest.

   Example of how your page might look:

   CodeOutput

   src/app/page.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import type { FC } from "react";import { IntlayerServerProvider } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {return (  <>    <p>Get started by editing</p>    <code>src/app/page.tsx</code>  </>);};export default async function Page() {const locale = await getLocale();return (  <IntlayerServerProvider locale={locale}>    <PageContent />  </IntlayerServerProvider>);}

   i18n/page-content.content.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   {key: "page-content",content: {  nodeType: "translation",  translation: {    en: {      getStartedByEditing: "Get started by editing",    },    fr: {      getStartedByEditing: "Commencez par éditer",    },    es: {      getStartedByEditing: "Comience editando",    },  }}}

   src/app/page.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import { type FC } from "react";import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {const content = useIntlayer("page-content");return (  <>    <p>{content.getStartedByEditing}</p>    <code>src/app/page.tsx</code>  </>);};export default async function Page() {const locale = await getLocale();return (  <IntlayerServerProvider locale={locale}>    <PageContent />  </IntlayerServerProvider>);}

   • IntlayerClientProvider is used to provide the locale to client-side components.

   • IntlayerServerProvider is used to provide the locale to the server children.

     Layout and page cannot share a common server context because the server context system is based on a per-request data store (via React's cache mechanism), causing each "context" to be re-created for different segments of the application. Placing the provider in a shared layout would break this isolation, preventing the correct propagation of the server context values to your server components.

7. 7

   Fill missing translation

   Optional

   Intlayer provide a CLI tool to help you fill missing translations. You can use the intlayer command to test and fill missing translations from your code.

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   npx intlayer test         # Test if there is missing translations

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   npx intlayer fill         # Fill missing translations

   For more details, refer to the CLI documentation

8. 8

   Configure Proxy for Locale Detection

   Optional

   Set up proxy to detect the user's preferred locale:

   src/proxy.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   export { intlayerProxy as proxy } from "next-intlayer/proxy";export const config = {  matcher:    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",};

   The intlayerProxy is used to detect the user's preferred locale and redirect them to the appropriate URL as specified in the configuration. Additionally, it enables saving the user's preferred locale in a cookie.

9. 8

   Change the language of your content

   Optional

   To change the language of your content in Next.js, the recommended way is to use the Link component to redirect users to the appropriate localized page. The Link component enables prefetching of the page, which helps avoid a full page reload.

   src/components/localeSwitcher/LocaleSwitcher.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   "use client";import type { FC } from "react";import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";import { useLocale } from "next-intlayer";export const LocaleSwitcher: FC = () => {  const { locale, availableLocales, setLocale } = useLocale();  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <button            key={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={() => setLocale(localeItem)}          >            <span>              {/* Locale - e.g. FR */}              {localeItem}            </span>            <span>              {/* Language in its own Locale - e.g. Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Language in current Locale - e.g. Francés with current locale set to Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Language in English - e.g. French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </button>        ))}      </div>    </div>  );};

   An alternative way is to use the setLocale function provided by the useLocale hook. This function will not allow prefetching the page. See the useLocale hook documentation for more details.

10. 10

    Optimize your bundle size

    Optional

    When using next-intlayer, dictionaries are included in the bundle for every page by default. To optimize bundle size, Intlayer provides an optional SWC plugin that intelligently replace useIntlayer calls using macros. This ensures dictionaries are only included in bundles for pages that actually use them.

    The @intlayer/babel plugin already integrate the bundling optimization (see babel.config.js). But the @intlayer/swc plugin is more performant. If you remove the @intlayer/babel plugin, you can use the @intlayer/swc plugin.

    Install the @intlayer/swc package. Once installed, next-intlayer will automatically detect and use the plugin:

    bash

    Copy content

    Copy code

    Copy the code to the clipboard

    npm install @intlayer/swc --save-dev

    Note: This optimization is only available for Next.js 13 and above.

    Note: This package is not installed by default because SWC plugins are still experimental on Next.js. It may change in the future.

    Note: If you set the option as importMode: 'dynamic' or importMode: 'fetch' (in the dictionary configuration), it will rely on Suspense, so you will have to wrap your useIntlayer calls in a Suspense boundary. That means, you will not be able to use the useIntlayer directly at the top level of your Page / Layout component.

11. 11

    Extract the content of your components

    Optional

    If you have an existing codebase, transforming thousands of files can be time-consuming.

    To ease this process, Intlayer propose a compiler / extractor to transform your components and extract the content.

    To set it up, you can add a compiler section in your intlayer.config.ts file:

    intlayer.config.ts

    Copy content

    Copy code

    Copy the code to the clipboard

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... Rest of your config
      compiler: {
        /**
         * Indicates if the compiler should be enabled.
         */
        enabled: true,
    
        /**
         * Defines the output files path
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * Indicates if the components should be saved after being transformed.
         *
         * - If `true`, the compiler will rewrite the component file in the disk. So the transformation will be permanent, and the compiler will skip the transformation for the next process. That way, the compiler can transform the app, and then it can be removed.
         *
         * - If `false`, the compiler will inject the `useIntlayer()` function call into the code in the build output only, and keep the base codebase intact. The transformation will be done only in memory.
         */
        saveComponents: false,
    
        /**
         * Dictionary key prefix
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;

    Extract commandBabel compiler

    Run the extractor to transform your components and extract the content

    bash

    Copy content

    Copy code

    Copy the code to the clipboard

    npx intlayer extract

    bash

    Copy content

    Copy code

    Copy the code to the clipboard

    npm install @intlayer/babel --save-dev

    babel.config.js

    Copy content

    Copy code

    Copy the code to the clipboard

    const { intlayerExtractBabelPlugin, getExtractPluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [   // Extract content from components into dictionaries   [intlayerExtractBabelPlugin, getExtractPluginOptions()], ],};

    bash

    Copy content

    Copy code

    Copy the code to the clipboard

    npm run build # Or npm run dev

Configure TypeScript

Intlayer use module augmentation to get benefits of TypeScript and make your codebase stronger.

Ensure your TypeScript configuration includes the autogenerated types.

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

Git Configuration

It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.

To do this, you can add the following instructions to your .gitignore file:

# Ignore the files generated by Intlayer.intlayer

VS Code Extension

To improve your development experience with Intlayer, you can install the official Intlayer VS Code Extension.

Install from the VS Code Marketplace

This extension provides:

• Autocompletion for translation keys.
• Real-time error detection for missing translations.
• Inline previews of translated content.
• Quick actions to easily create and update translations.

For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.

Go Further

To go further, you can implement the visual editor or externalize your content using the CMS.