Translate your Next.js 16 website (without [locale] in the page path) using Intlayer | Internationalization (i18n)

See Application Template on GitHub.

Table of Contents

What is Intlayer?

Intlayer is an innovative, open-source internationalization (i18n) library designed to simplify multilingual support in modern web applications. Intlayer seamlessly integrates with the latest Next.js 16 framework, including its powerful App Router. It is optimized to work with Server Components for efficient rendering and is fully compatible with Turbopack.

With Intlayer, you can:

• Easily manage translations using declarative dictionaries at the component level.
• Dynamically localize metadata, routes, and content.
• Access translations in both client-side and server-side components.
• Ensure TypeScript support with autogenerated types, improving autocompletion and error detection.
• Benefit from advanced features, like dynamic locale detection and switching.

Intlayer is compatible with Next.js 12, 13, 14, and 16. If you are using Next.js Page Router, you can refer to this guide. For Next.js 12, 13, 14 with App Router, refer to this guide.

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

Step 1: Install Dependencies

Install the necessary packages using npm:

npm install intlayer next-intlayernpx 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.

Step 2: Configure Your Project

Here is the final structure that we will make:

.├── src│   ├── app│   │   ├── layout.tsx│   │   ├── page.content.ts│   │   └── page.tsx│   ├── components│   │   ├── clientComponentExample│   │   │   ├── client-component-example.content.ts│   │   │   └── ClientComponentExample.tsx│   │   ├── localeSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   └── serverComponentExample│   │       ├── server-component-example.content.ts│   │       └── ServerComponentExample.tsx│   └── proxy.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

If you don't want locale routing, intlayer can be used as a simple provider / hook. See this guide for more details.

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

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Your other locales    ],    defaultLocale: Locales.ENGLISH,  },  routing: {    mode: "search-params", // or `no-prefix` - Useful for middleware detection  },};export default config;

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.

Step 3: Integrate Intlayer in Your Next.js Configuration

Configure your Next.js setup to use Intlayer:

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.

The withIntlayer() function is a promise function. It allows to prepare the intlayer dictionaries before the build starts. If you want to use it with other plugins, you can await it. Example:

const nextConfig = await withIntlayer(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

If you want to use it synchronously, you can use the withIntlayerSync() function. Example:

const nextConfig = withIntlayerSync(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

Intlayer automatically detects whether your project is using webpack or Turbopack based on the command-line flags --webpack, --turbo, or --turbopack, as well as your current Next.js version.

Since next>=16, if you are using Rspack, you must explicitly force Intlayer to use the webpack configuration by disabling Turbopack:

withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));

Step 4: Define Dynamic Locale Routes

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

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 ({  params,}: LocalPromiseParams): Promise<Metadata> => {  const { locale } = await params;  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;

Step 5: Declare Your Content

Create and manage your content declarations to store translations:

import { t, type Dictionary } from "intlayer";import { Metadata } from "next";const metadataContent = {  key: "metadata",  content: {    title: t({      en: "My Project Title",      fr: "Le Titre de mon Projet",      es: "El Título de mi Proyecto",    }),    description: t({      en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",      fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",      es: "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",    }),    keywords: t({      en: ["innovation", "productivity", "workflow", "SaaS"],      fr: ["innovation", "productivité", "flux de travail", "SaaS"],      es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],    }),  },} as Dictionary<Metadata>;export default metadataContent;

import { t, type Dictionary } from "intlayer";/** @type {import('intlayer').Dictionary<import('next').Metadata>} */const metadataContent = {  key: "metadata",  content: {    title: t({      en: "My Project Title",      fr: "Le Titre de mon Projet",      es: "El Título de mi Proyecto",    }),    description: t({      en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",      fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",      es: "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",    }),    keywords: t({      en: ["innovation", "productivity", "workflow", "SaaS"],      fr: ["innovation", "productivité", "flux de travail", "SaaS"],      es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],    }),  },};export default metadataContent;

import { t, type Dictionary } from "intlayer";const pageContent = {  key: "page",  content: {    getStarted: {      main: t({        en: "Get started by editing",        fr: "Commencez par éditer",        es: "Comience por editar",      }),      pageLink: "src/app/page.tsx",    },  },} satisfies Dictionary;export default pageContent;

Your content declarations can be defined anywhere in your application as soon they are included into the contentDir directory (by default, ./src). And match the content declaration file extension (by default, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

For more details, refer to the content declaration documentation.

Step 6: Utilize Content in Your Code

Access your content dictionaries throughout your application:

import type { FC } from "react";import { ClientComponentExample } from "@components/clientComponentExample/ClientComponentExample";import { ServerComponentExample } from "@components/serverComponentExample/ServerComponentExample";import {  IntlayerServerProvider,  useIntlayer,  getLocale,} from "next-intlayer/server";import { NextPage } from "next";import { headers, cookies } from "next/headers";const PageContent: FC = () => {  const content = useIntlayer("page");  return (    <>      <p>{content.getStarted.main}</p>      <code>{content.getStarted.pageLink}</code>    </>  );};const Page: NextPage = async () => {  const locale = await getLocale();  return (    <IntlayerServerProvider locale={locale}>      <PageContent />      <ServerComponentExample />      <ClientComponentExample />    </IntlayerServerProvider>  );};export default Page;

• IntlayerClientProvider is used to provide the locale to client-side components. It can be placed in any parent component, including the layout. However, placing it in a layout is recommended because Next.js shares layout code across pages, making it more efficient. By using IntlayerClientProvider in the layout, you avoid reinitializing it for every page, improving performance and maintaining a consistent localization context throughout your application.

• IntlayerServerProvider is used to provide the locale to the server children. It cannot be set set in the layout.

  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.

"use client";import type { FC } from "react";import { useIntlayer } from "next-intlayer";export const ClientComponentExample: FC = () => {  const content = useIntlayer("client-component-example"); // Create related content declaration  return (    <div>      <h2>{content.title}</h2>      <p>{content.content}</p>    </div>  );};

import type { FC } from "react";import { useIntlayer } from "next-intlayer/server";export const ServerComponentExample: FC = () => {  const content = useIntlayer("server-component-example"); // Create related content declaration  return (    <div>      <h2>{content.title}</h2>      <p>{content.content}</p>    </div>  );};

If you want to use your content in a string attribute, such as alt, title, href, aria-label, etc., you must call the value of the function, like:

<img src={content.image.src.value} alt={content.image.value} />

To Learn more about the useIntlayer hook, refer to the documentation.

(Optional) Step 7: Configure Proxy for Locale Detection

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

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.

If you need to chain several proxies together (for example, intlayerProxy with authentication or custom proxies), Intlayer now provides a helper called multipleProxies.

import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";import { customProxy } from "@utils/customProxy";export const proxy = multipleProxies([intlayerProxy, customProxy]);

(Optional) Step 8: Change the language of your content

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.

"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({    onChange: () => window.location.reload(),  });  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.

Documentation references:

• useLocale hook
• getLocaleName hook
• getLocalizedUrl hook
• getHTMLTextDir hook
• hrefLang attribute
• lang attribute
• dir attribute
• aria-current attribute

(Optional) Step 9: Get the current locale in Server Actions

If you need the active locale inside a Server Action (e.g., to localize emails or run locale-aware logic), call getLocale from next-intlayer/server:

"use server";import { getLocale } from "next-intlayer/server";export const myServerAction = async () => {  const locale = await getLocale();  // Do something with the locale};

The getLocale function follows a cascading strategy to determine the user's locale:

1. First, it checks the request headers for a locale value that may have been set by the proxy
2. If no locale is found in headers, it looks for a locale stored in cookies
3. If no cookie is found, it attempts to detect the user's preferred language from their browser settings
4. As a last resort, it falls back to the application's configured default locale

This ensures the most appropriate locale is selected based on available context.

(Optional) Step 10: Optmize your bundle size

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.

To enable this optimization, install the @intlayer/swc package. Once installed, next-intlayer will automatically detect and use the plugin:

npm install @intlayer/swc --save-devnpx intlayer init

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: 'live', 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.

Watch dictionaries changes on Turbopack

When using Turbopack as your development server with the next dev command, dictionary changes will not be automatically detected by default.

This limitation occurs because Turbopack cannot run webpack plugins in parallel to monitor changes in your content files. To work around this, you'll need to use the intlayer watch command to run both the development server and the Intlayer build watcher simultaneously.

{  // ... Your existing package.json configurations  "scripts": {    // ... Your existing scripts configurations    "dev": "intlayer watch --with 'next dev'",  },}

If you are using next-intlayer@<=6.x.x, you need to keep the --turbopack flag to make the Next.js 16 application work correctly with Turbopack. We recommend using next-intlayer@>=7.x.x to avoid this limitation.

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.