Creation:2024-12-06Last update:2026-05-31

    Traduire votre Next.js 14 and App Router avec Intlayer | Internationalisation (i18n)

    ide.intlayer.org

    Voir Application Template sur GitHub.

    Pourquoi Intlayer plutôt que des alternatives ?

    Par rapport aux solutions principales telles que next-intl ou i18next, Intlayer est une solution dotée d'optimisations intégrées telles que :

    Intlayer est optimisé pour fonctionner avec les composants serveur pour un rendu efficace et est entièrement compatible avec Turbopack. Il ne bloque pas le rendu statique et propose un middleware ainsi que toutes les fonctionnalités nécessaires à l'internationalisation à l'échelle (i18n).

    Intlayer est compatible avec Next.js 12, 13, 14, 15 et 16. Si vous utilisez le routeur de pages Next.js, vous pouvez vous référer à ce guide. Le routage local est utile pour le référencement, la taille du bundle et les performances. Si vous n'en avez pas besoin, vous pouvez vous référer à ce guide. Pour Next.js 12, 13, 14 et 15 avec App Router, reportez-vous à ce guide.

    Au lieu de charger de lourds fichiers JSON dans vos pages, ne chargez que le contenu strictement nécessaire. Intlayer vous aide à réduire la taille de votre bundle et de vos pages jusqu'à 50 %.

    Déclarer le contenu directement au plus près de vos composants facilite la maintenance des applications de grande envergure. Vous pouvez dupliquer ou supprimer le dossier d'une fonctionnalité sans le fardeau mental de devoir passer en revue toute votre base de code de contenu. De plus, Intlayer est entièrement typé pour garantir l'exactitude de vos traductions.

    La colocalisation du contenu réduit le contexte nécessaire aux grands modèles de langage (LLM). Intlayer est également livré avec une suite d'outils, tels qu'une CLI pour vérifier les traductions manquantes, un LSP, un MCP et des agent skills, afin de rendre l'expérience développeur (DX) encore plus fluide pour les agents IA.

    Automatisez les traductions dans votre pipeline CI/CD en utilisant le LLM de votre choix au coût de votre propre fournisseur d'IA. Intlayer propose également un compilateur pour automatiser l'extraction de contenu, ainsi qu'une plateforme web pour vous aider à traduire en arrière-plan.

    Associer de gros fichiers JSON à vos composants peut ralentir les performances et impacter la réactivité. Intlayer optimise le chargement du contenu directement au moment du build.

    Bien plus qu'une simple solution i18n, Intlayer propose un éditeur visuel auto-hébergé et un CMS complet pour gérer votre contenu multilingue en temps réel. Cela rend la collaboration avec les traducteurs, concepteurs-rédacteurs et autres membres de l'équipe extrêmement simple. Le contenu peut être stocké localement et/ou à distance.

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

    1. Installer les dépendances

      Installez les packages nécessaires avec npm :

      bash
      npm install intlayer next-intlayernpx intlayer init

      • intlayer

        Le package principal qui fournit des outils d'internationalisation pour la gestion des configurations, les traductions, 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 context providers et des hooks pour l'internationalisation de 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 rediriger les URL.

    2. Configurer votre projet

      Here is the final structure that we will make:

      bash
      .├── src│   ├── app│   │   ├── [locale]│   │   │   ├── layout.tsx            # Locale layout for the Intlayer provider│   │   │   ├── page.content.ts│   │   │   └── page.tsx│   │   └── layout.tsx                # Root layout for style and global providers│   ├── components│   │   ├── client-component-example.content.ts│   │   ├── ClientComponentExample.tsx│   │   ├── LocaleSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   ├── server-component-example.content.ts│   │   └── ServerComponentExample.tsx│   └── middleware.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.

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

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalisation: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Vos autres langues
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;
      Grâce à ce fichier de configuration, vous pouvez configurer des URL localisées, des redirections middleware, des noms de cookies, l'emplacement et l'extension de vos déclarations de contenu, désactiver les logs Intlayer dans la console, et bien plus encore. Pour une liste complète des paramètres disponibles, consultez la documentation de configuration.

    3. Intégrer Intlayer dans votre configuration Next.js

      Configurez votre projet Next.js pour utiliser Intlayer :

      next.config.mjs
      import { withIntlayer } from "next-intlayer/server";/** @type {import('next').NextConfig} */const nextConfig = {};export default withIntlayer(nextConfig);
      Le plugin withIntlayer() de Next.js est utilisé pour intégrer Intlayer avec Next.js. Il garantit 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 garantir la compatibilité avec les composants serveur.

    4. Configurer le middleware pour la détection de langue

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

      src/middleware.ts
      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 langue 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 langue préférée de l'utilisateur dans un cookie.
      Adaptez le paramètre matcher pour correspondre aux routes de votre application. Pour plus de détails, consultez la documentation Next.js sur la configuration du matcher.

    5. Définir des routes dynamiques pour les langues

      Supprimez tout le contenu de RootLayout et remplacez-le par le code suivant :

      src/app/layout.tsx
      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 langue en ajoutant une nouvelle mise en page dans votre répertoire [locale] :

      src/app/[locale]/layout.tsx
      import {
  type Next14LayoutIntlayer,
  IntlayerClientProvider,
} from "next-intlayer";
import { Inter } from "next/font/google";
import { getHTMLTextDir } from "intlayer";

const inter = Inter({ subsets: ["latin"] });

const LocaleLayout: Next14LayoutIntlayer = ({
  children,
  params: { locale },
}) => (
  <html lang={locale} dir={getHTMLTextDir(locale)}>
    <body className={inter.className}>
      <IntlayerClientProvider locale={locale}>
        {children}
      </IntlayerClientProvider>
    </body>
  </html>
);

export default LocaleLayout;
      Le segment de chemin [locale] est utilisé pour définir la langue. 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 4.

      Ensuite, implémentez la fonction generateStaticParams dans la mise en page de votre application.

      src/app/[locale]/layout.tsx
      export { generateStaticParams } from "next-intlayer"; // Ligne à insérer

const LocaleLayout: Next14LayoutIntlayer = ({
  children,
  params: { locale },
}) => {
  /*... Reste du code*/
};

export default LocaleLayout;
      generateStaticParams garantit que votre application pré-construit les pages nécessaires pour toutes les langues, réduisant ainsi les calculs au moment de l'exécution et améliorant l'expérience utilisateur. Pour plus de détails, consultez la documentation Next.js sur generateStaticParams.

    6. Déclarer votre contenu

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

      src/app/[locale]/page.content.ts
      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;
      Vos déclarations de contenu peuvent être définies n'importe où dans votre application tant 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,cjs}).
      Pour plus de détails, consultez la documentation sur les déclarations de contenu.

    7. Utiliser le contenu dans votre code

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

      src/app/[locale]/page.tsx
      import { ClientComponentExample } from "@components/ClientComponentExample";
import { ServerComponentExample } from "@components/ServerComponentExample";
import { type Next14PageIntlayer } from "next-intlayer";
import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";

const Page: Next14PageIntlayer = ({ params: { locale } }) => {
  const content = useIntlayer("page", locale);

  return (
    <>
      <p>
        {content.getStarted.main}
        <code>{content.getStarted.pageLink}</code>
      </p>

      <IntlayerServerProvider locale={locale}>
        <ServerComponentExample />
        <ClientComponentExample />
      </IntlayerServerProvider>
    </>
  );
};

export default Page;
      • IntlayerClientProvider est utilisé pour fournir la langue aux composants côté client. Il peut être placé dans n'importe quel composant parent, y compris la mise en page. Cependant, il est recommandé de le placer dans une mise en page car Next.js partage le code de mise en page entre les pages, ce qui le rend plus efficace. En utilisant IntlayerClientProvider dans la mise en page, 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 langue aux enfants côté serveur. Il ne peut pas être défini dans la mise en page.

        La mise en page 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 de cache de React), 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 propagation correcte des valeurs du contexte serveur à vos composants serveur.
      src/components/ClientComponentExample.tsx
      "use client";

import type { FC } from "react";
import { useIntlayer } from "next-intlayer";

const ClientComponentExample: FC = () => {
  const content = useIntlayer("client-component-example"); // Créez une déclaration de contenu associée

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};
      src/components/ServerComponentExample.tsx
      import type { FC } from "react";
import { useIntlayer } from "next-intlayer/server";

const ServerComponentExample: FC = () => {
  const content = useIntlayer("server-component-example"); // Créez une 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 string, tel que alt, title, href, aria-label, etc., vous devez appeler la valeur de la fonction, comme :
      html
      <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)}" />
      Pour en savoir plus sur le hook useIntlayer, consultez la documentation.

    8. Internationalisation de vos métadonnées

      Facultatif

      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 de la fonction, utilisez la fonction getTranslation pour traduire vos métadonnées.

      src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx
      import {  type IConfigLocales,  getTranslation,  getMultilingualUrls,} from "intlayer";import type { Metadata } from "next";import type { LocalParams } from "next-intlayer";export const generateMetadata = ({  params: { locale },}: LocalParams): Metadata => {  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);  /**   * Génère un objet contenant toutes les URL pour chaque langue.   *   * Exemple :   * ```ts   *  getMultilingualUrls('/about');   *   *  // Renvoie   *  // {   *  //   en: '/about',   *  //   fr: '/fr/about',   *  //   es: '/es/about',   *  // }   * ```   */  const multilingualUrls = getMultilingualUrls("/");  return {    title: t<string>({      en: "My title",      fr: "Mon titre",      es: "Mi título",    }),    description: t({      en: "My description",      fr: "Ma description",      es: "Mi descripción",    }),    alternates: {      canonical: multilingualUrls[locale as keyof typeof multilingualUrls],      languages: { ...multilingualUrls, "x-default": "/" },    },    openGraph: {      url: multilingualUrls[locale],    },  };};// ... Reste du code
      Pour en savoir plus sur l'optimisation des métadonnées sur la documentation officielle de Next.js.

    9. Internationalisation de votre sitemap.xml et robots.txt

      Facultatif

      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 URL multilingues pour votre sitemap.

      src/app/sitemap.ts
      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;
      src/app/robots.ts
      import type { MetadataRoute } from "next";
import { getMultilingualUrls } from "intlayer";

const getAllMultilingualUrls = (urls: string[]) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);

const robots = (): MetadataRoute.Robots => ({
  rules: {
    userAgent: "*",
    allow: ["/"],
    disallow: getAllMultilingualUrls(["/login", "/register"]),
  },
  host: "https://example.com",
  sitemap: `https://example.com/sitemap.xml`,
});

export default robots;
      Pour en savoir plus sur l'optimisation du sitemap sur la documentation officielle de Next.js. Pour en savoir plus sur l'optimisation du robots.txt sur la documentation officielle de Next.js.

    10. Changer la langue de votre contenu

      Facultatif

      Pour changer la langue de votre contenu, vous pouvez utiliser la fonction setLocale fournie par le hook useLocale. Cette fonction vous permet de définir la langue de l'application et de mettre à jour le contenu en conséquence.

      src/components/LocaleSwitcher.tsx
      "use client";

import {
  Locales,
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
} from "intlayer";
import { useLocale } from "next-intlayer";
import { type FC } from "react";
import Link from "next/link";

const LocaleSwitcher: FC = () => {
  const { locale, pathWithoutLocale, availableLocales, setLocale } =
    useLocale();

  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>
              {/* Langue - ex. FR */}
              {localeItem}
            </span>
            <span>
              {/* Langue dans son propre contexte - ex. Français */}
              {getLocaleName(localeItem, locale)}
            </span>
            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
              {/* Langue dans le contexte actuel - ex. Francés avec le contexte actuel défini sur Locales.SPANISH */}
              {getLocaleName(localeItem)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* Langue en anglais - ex. French */}
              {getLocaleName(localeItem, Locales.ENGLISH)}
            </span>
          </Link>
        ))}
      </div>
    </div>
  );
};

      Références de documentation :

    11. Créer un composant de lien localisé

      Facultatif

      Pour garantir que la navigation de votre application respecte la langue actuelle, vous pouvez créer un composant Link personnalisé. Ce composant préfixe automatiquement les URL internes avec la langue actuelle, de sorte que, 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 un 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 le contexte de la langue actuelle, évitant ainsi des changements de langue inattendus.
      • Maintenabilité : Centraliser la logique de localisation dans un seul composant simplifie la gestion des URL, rendant votre base de code plus facile à maintenir et à étendre à mesure que votre application se développe.

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

      src/components/Link.tsx
      "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";

/**
 * 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 langue actuelle.
 * Pour les liens internes, il utilise `getLocalizedUrl` pour préfixer l'URL avec la langue (par ex., /fr/about).
 * Cela garantit que la navigation reste dans le même contexte de langue.
 */
export const Link = forwardRef<
  HTMLAnchorElement,
  PropsWithChildren<NextLinkProps>
>(({ href, children, ...props }, ref: ForwardedRef<HTMLAnchorElement>) => {
  const { locale } = useLocale();
  const isExternalLink = checkIsExternalLink(href.toString());

  // Si le lien est interne et qu'un href valide est fourni, obtenez l'URL localisée.
  const hrefI18n: NextLinkProps["href"] =
    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;

  return (
    <NextLink href={hrefI18n} ref={ref} {...props}>
      {children}
    </NextLink>
  );
});

Link.displayName = "Link";

      Comment cela fonctionne

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

      • Récupération de la langue actuelle :
        Le hook useLocale fournit la langue actuelle (par ex., 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 langue actuelle. 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 langue.

      En intégrant ce composant Link dans toute votre application, vous maintenez une expérience utilisateur cohérente et respectueuse des langues tout en bénéficiant d'un meilleur SEO et d'une meilleure convivialité.

    12. Optimisez la taille de votre bundle

      Facultatif

      Lorsque vous utilisez next-intlayer, les dictionnaires sont inclus dans le bundle de chaque page par défaut. Pour optimiser la taille de votre bundle, Intlayer propose un plugin SWC optionnel qui remplace intelligemment les appels à useIntlayer à l'aide de 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 le détectera et l'utilisera automatiquement :

      bash
      npm install @intlayer/swc --save-dev
      Note: Cette optimisation n'est disponible que pour Next.js 13 et supérieur.

      Note: Ce paquet n'est pas installé par défaut car les plugins SWC sont encore expérimentaux sur Next.js. Cela peut changer dans le futur.

    Configurer TypeScript

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

    Autocompletion

    Translation error

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

    tsconfig.json
    {  // ... 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 ajouter à votre dépôt Git.

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

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

    Aller plus loin

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

    Next.js
    Next.js 15