Traduisez votre site Next.js 16 (sans [locale] dans le chemin des pages) avec Intlayer | Internationalisation (i18n)

Voir Application Template sur GitHub.

Table des matières

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 de manière transparente au dernier framework Next.js 16, y compris 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 d'erreurs.
• Profitez de fonctionnalités avancées, comme la détection dynamique de la locale et le basculement de langue.

Intlayer est compatible avec Next.js 12, 13, 14 et 16. Si vous utilisez le Page Router de Next.js, vous pouvez consulter ce guide. Pour Next.js 12, 13, 14 avec App Router, consultez ce guide.

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

Étape 1 : Installer les dépendances

Installez les packages nécessaires en utilisant npm :

npm install intlayer next-intlayernpx intlayer init

• 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 à Next.js. Il fournit des providers de contexte et des hooks pour l'internationalisation sous Next.js. De plus, il inclut le plugin Next.js pour intégrer Intlayer avec Webpack ou Turbopack, ainsi qu'un proxy pour détecter la locale préférée de l'utilisateur, gérer les cookies et gérer les redirections d'URL.

Étape 2 : Configurez votre projet

Voici la structure finale que nous allons créer :

.├── 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

Si vous ne voulez pas de routage par locale, intlayer peut être utilisé comme simple provider / hook. Voir ce guide pour plus de détails.

Créez un fichier de configuration pour définir 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,  },  routing: {    mode: "search-params", // ou `no-prefix` - Utile pour la détection par le middleware  },};export default config;

Grâce à ce fichier de configuration, vous pouvez configurer les URL localisées, la redirection proxy, les noms des cookies, l'emplacement et l'extension de vos déclarations de contenu, désactiver les logs d'Intlayer dans la console, et plus encore. Pour la liste complète des paramètres disponibles, consultez 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 à Next.js. Il assure la génération des fichiers de déclaration de contenu et les surveille en mode développement. Il définit les variables d'environnement d'Intlayer dans les environnements Webpack ou Turbopack. De plus, il fournit des alias pour optimiser les performances et garantit la compatibilité avec les server components.

La fonction withIntlayer() est une fonction retournant une Promise. Elle permet de préparer les dictionnaires Intlayer avant le démarrage de la build. Si vous souhaitez l'utiliser avec d'autres plugins, vous pouvez l'awaiter. Exemple:

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

Si vous souhaitez l'utiliser de manière synchrone, vous pouvez utiliser la fonction withIntlayerSync(). Exemple :

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

Intlayer détecte automatiquement si votre projet utilise webpack ou Turbopack en se basant sur les options de ligne de commande --webpack, --turbo ou --turbopack, ainsi que sur votre version de Next.js.

Depuis next>=16, si vous utilisez Rspack, vous devez explicitement forcer Intlayer à utiliser la configuration webpack en désactivant Turbopack :

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

Étape 4 : Définir des routes locales dynamiques

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

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;

É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";import { Metadata } from "next";const metadataContent = {  key: "metadata",  content: {    title: t({      fr: "Le titre de mon projet",      en: "My Project Title",      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({      fr: ["innovation", "productivité", "flux de travail", "SaaS"],      en: ["innovation", "productivity", "workflow", "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({      fr: "Le Titre de mon Projet",      en: "My Project Title",      es: "El Título de mi Proyecto",    }),    description: t({      fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",      en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",      es: "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",    }),    keywords: t({      fr: ["innovation", "productivité", "flux de travail", "SaaS"],      en: ["innovation", "productivity", "workflow", "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({        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, consultez la documentation sur les déclarations de contenu.

Étape 6 : Utiliser le contenu dans votre code

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

import type { FC } from "react";import { ClientComponentExample } from "@components/clientComponentExample/ClientComponentExample";import { ServerComponentExample } from "@components/serverComponentExample/ServerComponentExample";import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";import { NextPage } from "next";import { getLocale } from "intlayer";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 () => {  // Attendre les en-têtes et les cookies dans Next.js 15+  const headerList = await headers();  const cookieList = await cookies();  const locale = await getLocale({    // Vérifier d'abord le cookie intlayer (par défaut : 'INTLAYER_LOCALE')    getCookie: (name) => cookieList.get(name)?.value,    // Ensuite vérifier l'en-tête intlayer (par défaut : 'x-intlayer-locale')    // Et enfin vérifier l'en-tête accept-language ('accept-language')    getHeader: (name) => headerList.get(name),  });  return (    <IntlayerServerProvider locale={locale}>      <PageContent />      <ServerComponentExample />      <ClientComponentExample />    </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 des layouts 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éliorez les performances et maintenez 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 même contexte serveur, car le système de contextes serveur est basé sur un magasin de données par requête (via le mécanisme le 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é briserait cette isolation, empêchant la bonne propagation des valeurs du contexte serveur vers 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éer 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>  );};

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, par exemple :

<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 proxy pour la détection de la locale

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

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

Le intlayerProxy sert à détecter la locale préférée de l'utilisateur et à le rediriger vers l'URL appropriée, comme indiqué dans la configuration. De plus, il permet d'enregistrer la locale préférée de l'utilisateur dans un cookie.

Si vous devez chaîner plusieurs proxies (par exemple intlayerProxy avec une authentification ou des proxies personnalisés), Intlayer fournit désormais un helper appelé multipleProxies.

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

(Optionnel) Étape 8 : 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 (prefetch) de la page, ce qui aide à éviter un rechargement complet de la page.

"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 - ex. FR */}              {localeItem}            </span>            <span>              {/* Langue dans sa propre Locale - ex. Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Langue dans la locale courante - ex. "Francés" lorsque la locale courante est Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Langue en anglais - p.ex. French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </button>        ))}      </div>    </div>  );};

Une autre façon est d'utiliser la fonction setLocale fournie par le hook useLocale. Cette fonction n'autorisera pas le préchargement de la page. Consultez la documentation du hook useLocale pour plus de détails.

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 9 : Obtenir la locale courante dans les Server Actions

Si vous avez besoin de la locale active à l'intérieur d'une Server Action (par ex., pour localiser des e-mails ou exécuter une logique dépendante de la locale), appelez getLocale depuis next-intlayer/server :

"use server";import { getLocale } from "next-intlayer/server";export const myServerAction = async () => {  const locale = await getLocale();  // Faire quelque chose avec la locale};

La fonction getLocale suit une stratégie en cascade pour déterminer la locale de l'utilisateur :

1. D'abord, elle vérifie les en-têtes de la requête pour une valeur de locale qui peut avoir été définie par le proxy
2. Si aucune locale n'est trouvée dans les en-têtes, elle recherche une locale stockée dans les cookies
3. Si aucun cookie n'est trouvé, elle tente de détecter la langue préférée de l'utilisateur à partir des paramètres du navigateur
4. En dernier recours, elle revient à la locale par défaut configurée de l'application

Cela garantit que la locale la plus appropriée est sélectionnée en fonction du contexte disponible.

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

Lors de l'utilisation de next-intlayer, les dictionnaires sont inclus dans le bundle pour chaque page par défaut. Pour optimiser la taille du bundle, Intlayer fournit 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 paquet @intlayer/swc. Une fois installé, next-intlayer détectera et utilisera automatiquement le plugin :

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

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

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

Remarque : Si vous définissez l'option sur importMode: 'dynamic' ou importMode: 'live', cela reposera sur Suspense, vous devrez donc envelopper vos appels useIntlayer dans une frontière Suspense. Cela signifie que vous ne pourrez pas utiliser useIntlayer directement au niveau supérieur de votre composant Page / Layout.

Surveiller les modifications des dictionnaires sur Turbopack

Lorsque vous utilisez Turbopack comme serveur de développement avec la commande next dev, les modifications du dictionnaire ne seront pas détectées automatiquement par défaut.

Cette limitation survient parce que Turbopack ne peut pas exécuter les plugins webpack en parallèle pour surveiller les changements de vos fichiers de contenu. Pour contourner cela, vous devrez utiliser la commande intlayer watch afin d'exécuter simultanément le serveur de développement et le watcher de build d'Intlayer.

{  // ... Vos configurations existantes de package.json  "scripts": {    // ... Vos configurations de scripts existantes    "dev": "intlayer watch --with 'next dev'",  },}

Si vous utilisez next-intlayer@<=6.x.x, vous devez conserver le flag --turbopack pour que l'application Next.js 16 fonctionne correctement avec Turbopack. Nous recommandons d'utiliser next-intlayer@>=7.x.x pour éviter cette limitation.

Configurer TypeScript

Intlayer utilise le module augmentation pour bénéficier des avantages de TypeScript et renforcer votre codebase.

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 inclure dans votre dépôt Git.

Pour cela, vous pouvez ajouter les instructions suivantes à 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 VS Code Extension.

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 intégrés 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.