Premiers pas pour internationaliser (i18n) avec Intlayer et Next.js 15 App Router

<iframe title="La meilleure solution i18n pour Next.js ? Découvrez Intlayer" class="m-auto aspect-[16/9] w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/e_PPG7PTqGU?autoplay=0&amp;origin=http://intlayer.org&amp;controls=0&amp;rel=1"/>

Voir le Modèle d’Application sur GitHub.

Qu’est-ce qu’Intlayer ?

Intlayer est une bibliothèque d’internationalisation (i18n) innovante et open-source conçue pour simplifier la prise en charge multilingue dans les applications web modernes. Intlayer s’intègre parfaitement avec le dernier framework Next.js 15, incluant son puissant App Router. Il est optimisé pour fonctionner avec les Server Components pour un rendu efficace et est entièrement compatible avec Turbopack.

Avec Intlayer, vous pouvez :

• Gérer facilement les traductions en utilisant des dictionnaires déclaratifs au niveau des composants.
• Localiser dynamiquement les métadonnées, les routes et le contenu.
• Accéder aux traductions à la fois dans les composants côté client et côté serveur.
• Assurer la prise en charge de TypeScript avec des types générés automatiquement, améliorant l’autocomplétion et la détection des erreurs.
• Bénéficiez de fonctionnalités avancées, telles que la détection et le changement dynamique de la langue.

Intlayer est compatible avec Next.js 12, 13, 14 et 15. Si vous utilisez le Page Router de Next.js, vous pouvez consulter ce guide. Pour Next.js 12, 13, 14 avec App Router, référez-vous à ce guide.

Guide étape par étape pour configurer Intlayer dans une application Next.js

Étape 1 : Installer les dépendances

Installez les paquets nécessaires avec npm :

npm install intlayer next-intlayer

• intlayer

  Le package principal qui fournit des outils d'internationalisation pour la gestion de la configuration, la traduction, la déclaration de contenu, la transpilation, et les commandes CLI.

• next-intlayer

  Le package qui intègre Intlayer avec Next.js. Il fournit des fournisseurs de contexte et des hooks pour l'internationalisation dans Next.js. De plus, il inclut le plugin Next.js pour intégrer Intlayer avec Webpack ou Turbopack, ainsi qu'un middleware pour détecter la langue préférée de l'utilisateur, gérer les cookies et gérer la redirection des URL.

Étape 2 : Configurez votre projet

Créez un fichier de configuration pour configurer les langues de votre application :

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Vos autres locales    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

Grâce à ce fichier de configuration, vous pouvez configurer des URLs localisées, la redirection via middleware, les noms de cookies, l'emplacement et l'extension de vos déclarations de contenu, désactiver les logs Intlayer dans la console, et plus encore. Pour une liste complète des paramètres disponibles, référez-vous à la documentation de configuration.

Étape 3 : Intégrer Intlayer dans votre configuration Next.js

Configurez votre setup Next.js pour utiliser Intlayer :

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

Le plugin Next.js withIntlayer() est utilisé pour intégrer Intlayer avec Next.js. Il assure la construction des fichiers de déclaration de contenu et les surveille en mode développement. Il définit les variables d'environnement Intlayer dans les environnements Webpack ou Turbopack. De plus, il fournit des alias pour optimiser les performances et garantit la compatibilité avec les composants serveur.

Étape 4 : Définir les routes dynamiques de locale

Supprimez tout dans RootLayout et remplacez-le par le code suivant :

import type { PropsWithChildren, FC } from "react";import "./globals.css";const RootLayout: FC<PropsWithChildren> = ({ children }) => children;export default RootLayout;

Garder le composant RootLayout vide permet de définir les attributs lang et dir sur la balise <html>.

Pour implémenter le routage dynamique, fournissez le chemin pour la locale en ajoutant un nouveau layout dans votre répertoire [locale] :

import type { NextLayoutIntlayer } from "next-intlayer";import { Inter } from "next/font/google";import { getHTMLTextDir } from "intlayer";const inter = Inter({ subsets: ["latin"] });const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {  const { locale } = await params;  return (    <html lang={locale} dir={getHTMLTextDir(locale)}>      <body className={inter.className}>{children}</body>    </html>  );};export default LocaleLayout;

Le segment de chemin [locale] est utilisé pour définir la locale. Exemple : /en-US/about fera référence à en-US et /fr/about à fr.

À ce stade, vous rencontrerez l'erreur : Error: Missing <html> and <body> tags in the root layout.. Cela est attendu car le fichier /app/page.tsx n'est plus utilisé et peut être supprimé. À la place, le segment de chemin [locale] activera la page /app/[locale]/page.tsx. Par conséquent, les pages seront accessibles via des chemins comme /en, /fr, /es dans votre navigateur. Pour définir la locale par défaut comme page racine, référez-vous à la configuration du middleware à l'étape 7.

Ensuite, implémentez la fonction generateStaticParams dans le Layout de votre application.

Le segment de chemin [locale] est utilisé pour définir la locale. Exemple : /en-US/about fera référence à en-US et /fr/about à fr.

À ce stade, vous rencontrerez l'erreur : Error: Missing <html> and <body> tags in the root layout.. Cela est attendu car le fichier /app/page.tsx n'est plus utilisé et peut être supprimé. À la place, le segment de chemin [locale] activera la page /app/[locale]/page.tsx. Par conséquent, les pages seront accessibles via des chemins comme /en, /fr, /es dans votre navigateur. Pour définir la locale par défaut comme page racine, référez-vous à la configuration du middleware à l'étape 7.

Ensuite, implémentez la fonction generateStaticParams dans le Layout de votre application.

export { generateStaticParams } from "next-intlayer"; // Ligne à insérerconst LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {  /*... Reste du code */};export default LocaleLayout;

generateStaticParams garantit que votre application préconstruit les pages nécessaires pour toutes les locales, réduisant ainsi le calcul à l'exécution et améliorant l'expérience utilisateur. Pour plus de détails, consultez la documentation Next.js sur generateStaticParams.

Étape 5 : Déclarez Votre Contenu

Créez et gérez vos déclarations de contenu pour stocker les traductions :

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

Vos déclarations de contenu peuvent être définies n'importe où dans votre application dès qu'elles sont incluses dans le répertoire contentDir (par défaut, ./src). Et correspondent à l'extension de fichier de déclaration de contenu (par défaut, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Pour plus de détails, référez-vous à la documentation sur la déclaration de contenu.

Étape 6 : Utiliser le contenu dans votre code

Accédez à vos dictionnaires de contenu dans toute votre application :

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

• IntlayerClientProvider est utilisé pour fournir la locale aux composants côté client. Il peut être placé dans n'importe quel composant parent, y compris le layout. Cependant, il est recommandé de le placer dans un layout car Next.js partage le code du layout entre les pages, ce qui le rend plus efficace. En utilisant IntlayerClientProvider dans le layout, vous évitez de le réinitialiser pour chaque page, améliorant ainsi les performances et maintenant un contexte de localisation cohérent dans toute votre application.

• IntlayerServerProvider est utilisé pour fournir la locale aux enfants côté serveur. Il ne peut pas être défini dans le layout.

  Le layout et la page ne peuvent pas partager un contexte serveur commun car le système de contexte serveur est basé sur un magasin de données par requête (via le mécanisme cache de React), ce qui fait que chaque "contexte" est recréé pour différents segments de l'application. Placer le provider dans un layout partagé casserait cette isolation, empêchant la bonne propagation des valeurs du contexte serveur à vos composants serveur.

La mise en page (layout) et la page ne peuvent pas partager un contexte serveur commun car le système de contexte serveur est basé sur un magasin de données par requête (via le mécanisme React's cache), ce qui entraîne la recréation de chaque "contexte" pour différents segments de l'application. Placer le provider dans une mise en page partagée briserait cette isolation, empêchant la bonne propagation des valeurs du contexte serveur à vos composants serveur.

"use client";import type { FC } from "react";import { useIntlayer } from "next-intlayer";export const ClientComponentExample: FC = () => {  const content = useIntlayer("client-component-example"); // Crée la déclaration de contenu associée  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"); // Crée la déclaration de contenu associée  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"); // Créer la déclaration de contenu associée  return (    <div>      <h2>{content.title}</h2>      <p>{content.content}</p>    </div>  );};

Si vous souhaitez utiliser votre contenu dans un attribut de type string, tel que alt, title, href, aria-label, etc., vous devez appeler la valeur de la fonction, comme ceci :

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

Pour en savoir plus sur le hook useIntlayer, consultez la documentation.

(Optionnel) Étape 7 : Configurer le Middleware pour la détection de la langue

Configurez un middleware pour détecter la langue préférée de l'utilisateur :

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

Le intlayerMiddleware est utilisé pour détecter la locale préférée de l'utilisateur et le rediriger vers l'URL appropriée comme spécifié dans la configuration. De plus, il permet de sauvegarder la locale préférée de l'utilisateur dans un cookie.

(Optionnel) Étape 8 : Internationalisation de vos métadonnées

Dans le cas où vous souhaitez internationaliser vos métadonnées, telles que le titre de votre page, vous pouvez utiliser la fonction generateMetadata fournie par Next.js. À l'intérieur, vous pouvez récupérer le contenu depuis la fonction getIntlayer pour traduire vos métadonnées.

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

import { getIntlayer, getMultilingualUrls } from "intlayer";import type { Metadata } from "next";import type { LocalPromiseParams } from "next-intlayer";export const generateMetadata = async ({  params,}: LocalPromiseParams): Promise<Metadata> => {  const { locale } = await params;  const metadata = getIntlayer("page-metadata", locale);  /**   * Génère un objet contenant toutes les URL pour chaque locale.   *   * Exemple :   * ```ts   *  getMultilingualUrls('/about');   *   *  // Retourne   *  // {   *  //   en: '/about',   *  //   fr: '/fr/about',   *  //   es: '/es/about',   *  // }   * ```   */  const multilingualUrls = getMultilingualUrls("/");  return {    ...metadata,    alternates: {      canonical: multilingualUrls[locale as keyof typeof multilingualUrls],      languages: { ...multilingualUrls, "x-default": "/" },    },    openGraph: {      url: multilingualUrls[locale],    },  };};// ... Reste du code

Notez que la fonction getIntlayer importée depuis next-intlayer retourne votre contenu encapsulé dans un IntlayerNode, permettant l'intégration avec l'éditeur visuel. En revanche, la fonction getIntlayer importée depuis intlayer retourne votre contenu directement sans propriétés supplémentaires.

Alternativement, vous pouvez utiliser la fonction getTranslation pour déclarer vos métadonnées. Cependant, il est recommandé d'utiliser des fichiers de déclaration de contenu pour automatiser la traduction de vos métadonnées et externaliser le contenu à terme.

import {  type IConfigLocales,  getTranslation,  getMultilingualUrls,} from "intlayer";import type { Metadata } from "next";import type { LocalPromiseParams } from "next-intlayer";export const generateMetadata = async ({  params,}: LocalPromiseParams): Promise<Metadata> => {  const { locale } = await params;  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);  return {    title: t<string>({      fr: "Mon titre",      en: "My title",      es: "Mi título",    }),    description: t({      fr: "Ma description",      en: "My description",      es: "Mi descripción",    }),  };};// ... Suite du code

En savoir plus sur l'optimisation des métadonnées dans la documentation officielle de Next.js.

(Optionnel) Étape 9 : Internationalisation de votre sitemap.xml et robots.txt

Pour internationaliser votre sitemap.xml et robots.txt, vous pouvez utiliser la fonction getMultilingualUrls fournie par Intlayer. Cette fonction vous permet de générer des URLs multilingues pour votre sitemap.

import { getMultilingualUrls } from "intlayer";import type { MetadataRoute } from "next";const sitemap = (): MetadataRoute.Sitemap => [  {    url: "https://example.com",    alternates: {      languages: { ...getMultilingualUrls("https://example.com") },    },  },  {    url: "https://example.com/login",    alternates: {      languages: { ...getMultilingualUrls("https://example.com/login") },    },  },  {    url: "https://example.com/register",    alternates: {      languages: { ...getMultilingualUrls("https://example.com/register") },    },  },];export default sitemap;

import type { MetadataRoute } from "next";import { getMultilingualUrls } from "intlayer";const getAllMultilingualUrls = (urls: string[]) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);// Règles pour le fichier robots.txtconst robots = (): MetadataRoute.Robots => ({  rules: {    userAgent: "*",    allow: ["/"],    disallow: getAllMultilingualUrls(["/login", "/register"]),  },  host: "https://example.com",  sitemap: `https://example.com/sitemap.xml`,});export default robots;

En savoir plus sur l'optimisation du sitemap dans la documentation officielle de Next.js. En savoir plus sur l'optimisation du fichier robots.txt dans la documentation officielle de Next.js.

(Optionnel) Étape 10 : Changer la langue de votre contenu

Pour changer la langue de votre contenu dans Next.js, la méthode recommandée est d'utiliser le composant Link pour rediriger les utilisateurs vers la page localisée appropriée. Le composant Link permet le préchargement de la page, ce qui évite un rechargement complet.

"use client";import type { FC } from "react";import {  Locales,  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,} from "intlayer";import { useLocale } from "next-intlayer";import Link from "next/link";export const LocaleSwitcher: FC = () => {  const { locale, pathWithoutLocale, availableLocales } = useLocale();  const { setLocaleCookie } = useLocaleCookie();  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={() => setLocaleCookie(localeItem)}          >            <span>              {/* Locale - par ex. FR */}              {localeItem}            </span>            <span>              {/* Langue dans sa propre locale - par ex. Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Langue dans la locale courante - par ex. Francés avec la locale courante définie sur Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Langue en anglais - par ex. French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </Link>        ))}      </div>    </div>  );};

Une autre façon est d'utiliser la fonction setLocale fournie par le hook useLocale. Cette fonction ne permettra pas le préchargement de la page et rechargera la page.

Dans ce cas, sans redirection via router.push, seul votre code côté serveur changera la locale du contenu.

"use client";import { useRouter } from "next/navigation";import { useLocale } from "next-intlayer";import { getLocalizedUrl } from "intlayer";// ... Reste du codeconst router = useRouter();const { setLocale } = useLocale({  onLocaleChange: (locale) => {    router.push(getLocalizedUrl(pathWithoutLocale, locale));  },});return (  <button onClick={() => setLocale(Locales.FRENCH)}>Changer en français</button>);

Références de la documentation :

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

(Optionnel) Étape 11 : Création d'un composant Link localisé

Pour garantir que la navigation de votre application respecte la langue courante, vous pouvez créer un composant Link personnalisé. Ce composant préfixe automatiquement les URL internes avec la langue actuelle. Par exemple, lorsqu'un utilisateur francophone clique sur un lien vers la page "À propos", il est redirigé vers /fr/about au lieu de /about.

Ce comportement est utile pour plusieurs raisons :

• SEO et expérience utilisateur : Les URL localisées aident les moteurs de recherche à indexer correctement les pages spécifiques à une langue et fournissent aux utilisateurs du contenu dans leur langue préférée.
• Cohérence : En utilisant un lien localisé dans toute votre application, vous garantissez que la navigation reste dans la langue courante, évitant ainsi des changements de langue inattendus.
• Maintenabilité : Centraliser la logique de localisation dans un seul composant simplifie la gestion des URLs, rendant votre base de code plus facile à maintenir et à étendre au fur et à mesure que votre application grandit.

Voici l'implémentation d'un composant Link localisé en TypeScript :

"use client";import { getLocalizedUrl } from "intlayer";import NextLink, { type LinkProps as NextLinkProps } from "next/link";import { useLocale } from "next-intlayer";import type { PropsWithChildren, FC } from "react";/** * Fonction utilitaire pour vérifier si une URL donnée est externe. * Si l'URL commence par http:// ou https://, elle est considérée comme externe. */export const checkIsExternalLink = (href?: string): boolean =>  /^https?:\/\//.test(href ?? "");/** * Un composant Link personnalisé qui adapte l'attribut href en fonction de la locale actuelle. * Pour les liens internes, il utilise `getLocalizedUrl` pour préfixer l'URL avec la locale (par exemple, /fr/about). * Cela garantit que la navigation reste dans le même contexte de locale. */export const Link: FC<PropsWithChildren<NextLinkProps>> = ({  href,  children,  ...props}) => {  const { locale } = useLocale();  const isExternalLink = checkIsExternalLink(href.toString());  // Si le lien est interne et qu'un href valide est fourni, obtenir l'URL localisée.  const hrefI18n: NextLinkProps["href"] =    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;  return (    <NextLink href={hrefI18n} {...props}>      {children}    </NextLink>  );};

Comment ça fonctionne

• Détection des liens externes :

• Détection des liens externes :
  La fonction utilitaire checkIsExternalLink détermine si une URL est externe. Les liens externes restent inchangés car ils ne nécessitent pas de localisation.

• Récupération de la locale courante :
  Le hook useLocale fournit la locale actuelle (par exemple, fr pour le français).

• Localisation de l'URL :
  Pour les liens internes (c’est-à-dire non externes), getLocalizedUrl est utilisé pour préfixer automatiquement l’URL avec la locale courante. Cela signifie que si votre utilisateur est en français, passer /about comme href le transformera en /fr/about.

• Retour du lien :
  Le composant retourne un élément <a> avec l’URL localisée, garantissant que la navigation est cohérente avec la locale.

En intégrant ce composant Link dans toute votre application, vous maintenez une expérience utilisateur cohérente et adaptée à la langue, tout en bénéficiant d'une meilleure optimisation SEO et d'une meilleure utilisabilité.

(Optionnel) Étape 12 : Optimisez la taille de votre bundle

Lors de l'utilisation de next-intlayer, les dictionnaires sont inclus par défaut dans le bundle de chaque page. Pour optimiser la taille du bundle, Intlayer propose un plugin SWC optionnel qui remplace intelligemment les appels à useIntlayer en utilisant des macros. Cela garantit que les dictionnaires ne sont inclus que dans les bundles des pages qui les utilisent réellement.

Pour activer cette optimisation, installez le package @intlayer/swc. Une fois installé, next-intlayer détectera automatiquement et utilisera le plugin :

npm install @intlayer/swc --save-dev

Remarque : Cette optimisation est uniquement disponible pour Next.js 13 et versions supérieures.

Remarque : Ce paquet n'est pas installé par défaut car les plugins SWC sont encore expérimentaux sur Next.js. Cela pourrait changer à l'avenir.

Configurer TypeScript

Intlayer utilise l'augmentation de module pour bénéficier de TypeScript et renforcer votre base de code.

Assurez-vous que votre configuration TypeScript inclut les types générés automatiquement.

{  // ... Vos configurations TypeScript existantes  "include": [    // ... Vos configurations TypeScript existantes    ".intlayer/**/*.ts", // Inclure les types générés automatiquement  ],}

Configuration Git

Il est recommandé d'ignorer les fichiers générés par Intlayer. Cela vous permet d'éviter de les commettre dans votre dépôt Git.

Pour ce faire, vous pouvez ajouter les instructions suivantes dans votre fichier .gitignore :

# Ignorer les fichiers générés par Intlayer.intlayer

Extension VS Code

Pour améliorer votre expérience de développement avec Intlayer, vous pouvez installer l'extension officielle Intlayer pour VS Code.

Installer depuis le Marketplace VS Code

Cette extension offre :

• Autocomplétion pour les clés de traduction.
• Détection d'erreurs en temps réel pour les traductions manquantes.
• Aperçus en ligne du contenu traduit.
• Actions rapides pour créer et mettre à jour facilement les traductions.

Pour plus de détails sur l'utilisation de l'extension, consultez la documentation de l'extension VS Code Intlayer.

Aller plus loin

Pour aller plus loin, vous pouvez implémenter l'éditeur visuel ou externaliser votre contenu en utilisant le CMS.

Historique de la documentation

• 5.5.10 - 2025-06-29 : Historique initial