Getting Started Internationalising (i18n) with Intlayer and Next.js using Page Router

Table of Contents

Why Intlayer over alternatives?

Compared to main solutions like next-intl or i18next, Intlayer is a solution that comes with integrated optimizations such as:

Step-by-Step Guide to Set Up Intlayer in a Next.js Application Using the Page Router

1. 1

   Install Dependencies

   Install the necessary packages using your preferred package manager:

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   npx intlayer init --interactive
   

   the --interactive flag is optional. Use intlayer-cli init if you're an AI agent.

   This command will detect your environment and install the required packages. For example:

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   npm install intlayer next-intlayer
   

   • intlayer

     The core package that provides internationalisation 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 internationalisation. Additionally, it includes the Next.js plugin for integrating Intlayer with Webpack or Turbopack, as well as middleware for detecting the user's preferred locale, managing cookies, and handling URL redirection.

2. 2

   Configure Your Project

   Create a configuration file to define the languages supported by 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,
         Locales.SPANISH,
         // Add your other locales here
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;
   

   Through this configuration file, you can set up localised URLs, middleware 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 with Next.js Configuration

   Modify your Next.js configuration to incorporate Intlayer:

   next.config.mjs

   Copy content

   Copy code

   Copy the code to the clipboard

   import { withIntlayer } from "next-intlayer/server";
   
   /** @type {import('next').NextConfig} */
   const nextConfig = {
     // Your existing Next.js configuration
   };
   
   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 optimise performance and ensures compatibility with server components.

   The withIntlayer() function is a promise function. If you want to use it with other plugins, you can await it. Example:

   tsx

   Copy content

   Copy code

   Copy the code to the clipboard

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

4. 4

   Configure Middleware for Locale Detection

   Set up middleware to automatically detect and handle the user's preferred locale:

   Since Intlayer v9, this middleware respects the routing.enableProxy option (true by default). Set routing.enableProxy: false in your configuration to turn it into a pass-through without removing this file. See the v9 release notes.

   src/middleware.ts

   Copy content

   Copy code

   Copy the code to the clipboard

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

   Adapt the matcher parameter to match the routes of your application. For more details, refer to the Next.js documentation on configuring the matcher.

5. 5

   Define Dynamic Locale Routes

   Implement dynamic routing to serve localised content based on the user's locale.

   1. Create Locale-Specific Pages:

      Rename your main page file to include the [locale] dynamic segment.

      bash

      Copy content

      Copy code

      Copy the code to the clipboard

      mv src/pages/index.tsx src/pages/[locale]/index.tsx
      

   2. Update _app.tsx to Handle Localisation:

      plaintext

      Copy content

      Copy code

      Copy the code to the clipboard

      Modify your `_app.tsx` to include Intlayer providers.
      
      ```tsx fileName="src/pages/_app.tsx" codeFormat="typescript"
      import type { FC } from "react";
      import type { AppProps } from "next/app";
      import { IntlayerClientProvider } from "next-intlayer";
      
      const App = FC<AppProps>({ Component, pageProps }) => {
        const { locale } = pageProps;
      
        return (
          <IntlayerClientProvider locale={locale}>
            <Component {...pageProps} />
          </IntlayerClientProvider>
        );
      }
      
      export default MyApp;
      ```

   3. Set Up getStaticPaths and getStaticProps:

      In your [locale]/index.tsx, define the paths and props to manage different locales.

      src/pages/[locale]/index.tsx

      Copy content

      Copy code

      Copy the code to the clipboard

      import type { FC } from "react";
      import type { GetStaticPaths, GetStaticProps } from "next";
      import { type Locales, getConfiguration } from "intlayer";
      
      const HomePage: FC = () => <div>{/* Your content here */}</div>;
      
      export const getStaticPaths: GetStaticPaths = () => {
        const { internationalization } = getConfiguration();
        const { locales } = internationalization;
      
        const paths = locales.map((locale) => ({
          params: { locale },
        }));
      
        return { paths, fallback: false };
      };
      
      export const getStaticProps: GetStaticProps = ({ params }) => {
        const locale = params?.locale as string;
      
        return {
          props: {
            locale,
          },
        };
      };
      
      export default HomePage;
      

   getStaticPaths and getStaticProps ensure that your application pre-builds the necessary pages for all locales in Next.js Page Router. This approach reduces runtime computation and leads to an improved user experience. For more details, refer to the Next.js documentation on getStaticPaths and getStaticProps.

6. 6

   Declare Your Content

   Create and manage your content declarations to store translations.

   src/pages/[locale]/home.content.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import { t, type Dictionary } from "intlayer";
   
   const homeContent = {
     key: "home",
     content: {
       title: t({
         "en-GB": "Welcome to My Website",
         en: "Welcome to My Website",
         fr: "Bienvenue sur mon site Web",
         es: "Bienvenido a mi sitio web",
       }),
       description: t({
         "en-GB": "Get started by editing this page.",
         en: "Get started by editing this page.",
         fr: "Commencez par éditer cette page.",
         es: "Comience por editar esta página.",
       }),
     },
   } satisfies Dictionary;
   
   export default homeContent;
   

   For more information on declaring content, refer to the content declaration guide.

7. 7

   Utilise Content in Your Code

   Access your content dictionaries throughout your application to display translated content.

   src/pages/[locale]/index.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import type { FC } from "react";
   import { useIntlayer } from "next-intlayer";
   import { ComponentExample } from "@components/ComponentExample";
   
   const HomePage: FC = () => {
     const content = useIntlayer("home");
   
     return (
       <div>
         <h1>{content.title}</h1>
         <p>{content.description}</p>
         <ComponentExample />
         {/* Additional components */}
       </div>
     );
   };
   
   // ... Rest of the code, including getStaticPaths and getStaticProps
   
   export default HomePage;
   

   When using translations in string attributes (e.g., alt, title, href, aria-label), call the

   value of the function as follows:

   html

   Copy content

   Copy code

   Copy the code to the clipboard

   <img src="{content.image.src.value}" alt="{content.image.value}" />
   <img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
   <img src="{String(content.image.src)}" alt="{String(content.image)}" />
   

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

8. 8

   Internationalisation of your metadata

   Optional

   If you want to internationalise your metadata, such as the title of your page, you can use the getStaticProps function provided by Next.js Page Router. Within this, you can retrieve the content from the getIntlayer function to translate your metadata.

   src/pages/[locale]/metadata.content.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import { type Dictionary, t } from "intlayer";
   import { type Metadata } from "next";
   
   const metadataContent = {
     key: "page-metadata",
     content: {
       title: t({
         en: "Create Next App",
         fr: "Créer une application Next.js",
         es: "Crear una aplicación Next.js",
       }),
       description: t({
         en: "Generated by create next app",
         fr: "Généré par create next app",
         es: "Generado por create next app",
       }),
     },
   } satisfies Dictionary<Metadata>;
   
   export default metadataContent;
   

   src/pages/[locale]/index.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import { GetStaticPaths, GetStaticProps } from "next";
   import { getIntlayer, getMultilingualUrls } from "intlayer";
   import { useIntlayer } from "next-intlayer";
   import Head from "next/head";
   import type { FC } from "react";
   
   interface HomePageProps {
     locale: string;
     metadata: {
       title: string;
       description: string;
     };
     multilingualUrls: Record<string, string>;
   }
   
   const HomePage: FC<HomePageProps> = ({
     metadata,
     multilingualUrls,
     locale,
   }) => {
     const content = useIntlayer("page");
   
     return (
       <div>
         <Head>
           <title>{metadata.title}</title>
           <meta name="description" content={metadata.description} />
           {/* Generate hreflang tags for SEO */}
           {Object.entries(multilingualUrls).map(([lang, url]) => (
             <link key={lang} rel="alternate" hrefLang={lang} href={url} />
           ))}
           <link rel="canonical" href={multilingualUrls[locale]} />
         </Head>
   
         {/* Page content */}
         <main>{/* Your page content here */}</main>
       </div>
     );
   };
   
   export const getStaticProps: GetStaticProps<HomePageProps> = async ({
     params,
   }) => {
     const locale = params?.locale as string;
   
     const metadata = getIntlayer("page-metadata", locale);
   
     /**
      * Generates an object containing all URLs for each locale.
      *
      * Example:
      * ```ts
      *  getMultilingualUrls('/about');
      *
      *  // Returns
      *  // {
      *  //   en: '/about',
      *  //   fr: '/fr/about',
      *  //   es: '/es/about',
      *  // }
      * ```
      */
     const multilingualUrls = getMultilingualUrls("/");
   
     return {
       props: {
         locale,
         metadata,
         multilingualUrls,
       },
     };
   };
   
   export default HomePage;
   
   // ... Rest of the code including getStaticPaths
   

   Note that the getIntlayer function imported from next-intlayer returns your content wrapped in an IntlayerNode, allowing integration with the visual editor. In contrast, the getIntlayer function imported from intlayer returns your content directly without additional properties.

   Learn more about the metadata optimisation on the official Next.js documentation.

9. 9

   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 localised page. The Link component enables prefetching of the page, which helps avoid a full page reload.

   src/components/LanguageSwitcher.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import {
     Locales,
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
   } from "intlayer";
   import { useLocalePageRouter } from "next-intlayer";
   import { type FC } from "react";
   import Link from "next/link";
   
   const LocaleSwitcher: FC = () => {
     const { locale, pathWithoutLocale, availableLocales } = useLocalePageRouter();
   
     return (
       <div>
         <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
         <div id="localePopover" popover="auto">
           {availableLocales.map((localeItem) => (
             <Link
               href={getLocalizedUrl(pathWithoutLocale, localeItem)}
               hrefLang={localeItem}
               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>
             </Link>
           ))}
         </div>
       </div>
     );
   };
   

   An alternative method is to use the setLocale function provided by the useLocale hook. This function will not permit prefetching the page and will reload the page.

   In this case, without redirection using router.push, only your server-side code will change the locale of the content.

   src/components/LocaleSwitcher.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   "use client";
   
   import { useLocale } from "next-intlayer";
   import { getLocalizedUrl } from "intlayer";
   
   // ... Rest of the code
   
   const { setLocale } = useLocale();
   
   return (
     <button onClick={() => setLocale(Locales.FRENCH)}>Change to French</button>
   );
   

   The useLocalePageRouter API is the same as useLocale. To learn more about the useLocale hook, refer to the documentation.

   Documentation references:

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

10. 10

    Creating a Localised Link Component

    Optional

    To ensure that your application’s navigation respects the current locale, you can create a custom Link component. This component automatically prefixes internal URLs with the current language. For example, when a French-speaking user clicks on a link to the "About" page, they are redirected to /fr/about instead of /about.

    This behaviour is useful for several reasons:

    • SEO and User Experience: Localised URLs help search engines index language-specific pages correctly and provide users with content in their preferred language.
    • Consistency: By using a localised link throughout your application, you guarantee that navigation stays within the current locale, preventing unexpected language switches.
    • Maintainability: Centralising the localisation logic in a single component simplifies the management of URLs, making your codebase easier to maintain and extend as your application grows.

    Below is the implementation of a localised Link component in TypeScript:

    src/components/Link.tsx

    Copy content

    Copy code

    Copy the code to the clipboard

    "use client";
    
    import { getLocalizedUrl } from "intlayer";
    import NextLink, { type LinkProps as NextLinkProps } from "next/link";
    import { useLocale } from "next-intlayer";
    import { forwardRef, PropsWithChildren, type ForwardedRef } from "react";
    
    /**
     * Utility function to check whether a given URL is external.
     * If the URL starts with http:// or https://, it is considered external.
     */
    export const checkIsExternalLink = (href?: string): boolean =>
      /^https?:\/\//.test(href ?? "");
    
    /**
     * A custom Link component that adapts the href attribute based on the current locale.
     * For internal links, it uses `getLocalizedUrl` to prefix the URL with the locale (e.g., /fr/about).
     * This ensures that navigation stays within the same locale context.
     */
    export const Link = forwardRef<
      HTMLAnchorElement,
      PropsWithChildren<NextLinkProps>
    >(({ href, children, ...props }, ref: ForwardedRef<HTMLAnchorElement>) => {
      const { locale } = useLocale();
      const isExternalLink = checkIsExternalLink(href.toString());
    
      // If the link is internal and a valid href is provided, get the localised URL.
      const hrefI18n: NextLinkProps["href"] =
        href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;
    
      return (
        <NextLink href={hrefI18n} ref={ref} {...props}>
          {children}
        </NextLink>
      );
    });
    
    Link.displayName = "Link";
    

    How It Works

    • Detecting External Links:
      The helper function checkIsExternalLink determines whether a URL is external. External links are left unchanged because they do not require localisation.

    • Retrieving the Current Locale:
      The useLocale hook provides the current locale (e.g., fr for French).

    • Localising the URL:
      For internal links (i.e., non-external), getLocalizedUrl is used to automatically prefix the URL with the current locale. This means that if your user is in French, passing /about as the href will transform it to /fr/about.

    • Returning the Link:
      The component returns an <a> element with the localised URL, ensuring that navigation is consistent with the locale.

    By integrating this Link component across your application, you maintain a coherent and language-aware user experience while also benefitting from improved SEO and usability.

11. 11

    Optimise your bundle size

    Optional

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

    To enable this optimisation, 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 optimisation 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. This may change in the future.

Configure TypeScript

Intlayer uses module augmentation to leverage the benefits of TypeScript and strengthen your codebase.

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

To keep your repository clean and avoid committing generated files, it is recommended to ignore files created by Intlayer.

Add the following lines to your .gitignore file:

# Ignore the files generated by Intlayer
.intlayer

VS Code Extension

To enhance 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.

Additional Resources

• Intlayer Documentation: GitHub Repository
• Dictionary Guide: Dictionary
• Configuration Documentation: Configuration Guide

By following this guide, you can effectively integrate Intlayer into your Next.js application using the Page Router, enabling robust and scalable internationalisation support for your web projects.

Go Further

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

Frequently Asked Questions