Documentation

Environnement

Intlayer avec Next.js

Commencer à internationaliser (i18n) avec Intlayer et Next.js 15 App Router

Qu'est-ce qu'Intlayer ?

Intlayer est une bibliothèque innovante et open-source d'internationalisation (i18n) conçue pour simplifier le support multilingue dans les applications web modernes. Intlayer s'intègre parfaitement avec le dernier framework Next.js 15, 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 du composant.
Localiser dynamiquement les métadonnées, les routes et le contenu.
Accéder aux traductions dans les composants côté client et côté serveur.
Assurer la prise en charge de TypeScript avec des types autogénérés, améliorant l'autocomplétion et la détection d'erreurs.
Profiter de fonctionnalités avancées, comme la détection et le changement dynamiques de locale.

Remarque : Intlayer est compatible avec Next.js 12, 13, 14 et 15. Si vous utilisez Next.js Page Router, vous pouvez vous référer à ce guide. Pour Next.js 12, 13, 14 avec App Router, reportez-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 en utilisant npm :

bash

1npm install intlayer next-intlayer

bash

1yarn add intlayer next-intlayer

bash

1pnpm add intlayer next-intlayer

Étape 2 : Configurer votre projet

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

typescript

1// intlayer.config.ts
2
3import { Locales, type IntlayerConfig } from "intlayer";
4
5const config: IntlayerConfig = {
6  internationalization: {
7    locales: [
8      Locales.ENGLISH,
9      Locales.FRENCH,
10      Locales.SPANISH,
11      // Vos autres locales
12    ],
13    defaultLocale: Locales.ENGLISH,
14  },
15};
16
17export default config;

Pour voir tous les paramètres disponibles, consultez la documentation de configuration ici.

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

Configurez votre installation Next.js pour utiliser Intlayer :

typescript

1// next.config.mjs
2import { withIntlayer } from "next-intlayer/server";
3
4/** @type {import('next').NextConfig} */
5const nextConfig = {};
6
7export default withIntlayer(nextConfig);

Étape 4 : Configurer le middleware pour la détection de locale

Mettez en place un middleware pour détecter la locale préférée de l'utilisateur :

typescript

1// src/middleware.ts
2export { intlayerMiddleware as middleware } from "next-intlayer/middleware";
3
4export const config = {
5  matcher: "/((?!api|static|.*\\..*|_next).*)",
6};

Étape 5 : Définir des routes dynamiques pour les locales

Implémentez un routage dynamique pour un contenu localisé :

Changez src/app/page.ts en src/app/[locale]/page.ts

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

tsx

1// src/app/layout.tsx
2
3import type { ReactNode } from "react";
4import "./globals.css";
5
6export { generateStaticParams } from "next-intlayer"; // Ligne à insérer
7
8const RootLayout = ({
9  children,
10}: Readonly<{
11  children: ReactNode;
12}>) => children;
13
14export default RootLayout;

Ajoutez ensuite un nouveau layout dans votre répertoire [locale] :

tsx

1// src/app/[locale]/layout.tsx
2
3import { type NextLayoutIntlayer } from "next-intlayer";
4import { Inter } from "next/font/google";
5import { getHTMLTextDir } from "intlayer";
6
7const inter = Inter({ subsets: ["latin"] });
8
9const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
10  const { locale } = await params;
11  return (
12    <html lang={locale} dir={getHTMLTextDir(locale)}>
13      <body className={inter.className}>{children}</body>
14    </html>
15  );
16};
17
18export default LocaleLayout;

Étape 6 : Déclarer votre contenu

Créez et gérez vos dictionnaires de contenu :

tsx

1// src/app/[locale]/page.content.ts
2import { t, type DeclarationContent } from "intlayer";
3
4const pageContent = {
5  key: "page",
6  content: {
7    getStarted: {
8      main: t({
9        en: "Get started by editing",
10        fr: "Commencez par éditer",
11        es: "Comience por editar",
12      }),
13      pageLink: "src/app/page.tsx",
14    },
15  },
16} satisfies DeclarationContent;
17
18export default pageContent;

Voir comment déclarer vos fichiers de déclaration Intlayer.

Étape 7 : Utiliser le contenu dans votre code

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

tsx

1// src/app/[locale]/page.ts
2
3import { ClientComponentExample } from "@component/ClientComponentExample";
4import { LocaleSwitcher } from "@component/LangSwitcherDropDown";
5import { NestedServerComponentExample } from "@component/NestedServerComponentExample";
6import { ServerComponentExample } from "@component/ServerComponentExample";
7import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";
8import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
9
10const PageContent = () => {
11  const { title, content } = useIntlayer("page");
12
13  return (
14    <>
15      <p>{content.getStarted.main}</p>
16      <code>{content.getStarted.pageLink}</code>
17    </>
18  );
19};
20
21const Page: NextPageIntlayer = async ({ params }) => {
22  const { locale } = await params;
23
24  return (
25    <>
26      {/**
27       *   IntlayerServerProvider est utilisé pour fournir la locale aux enfants du serveur
28       *   Ne fonctionne pas s'il est défini dans la mise en page
29       */}
30      <IntlayerServerProvider locale={locale}>
31        <PageContent />
32        <ServerComponentExample />
33      </IntlayerServerProvider>
34      {/**
35       *   IntlayerClientProvider est utilisé pour fournir la locale aux enfants du client
36       *   Peut être défini dans n'importe quel composant parent, y compris la mise en page
37       */}
38      <IntlayerClientProvider locale={locale}>
39        <ClientComponentExample />
40      </IntlayerClientProvider>
41    </>
42  );
43};
44
45export default Page;

tsx

1// src/components/ClientComponentExample.tsx
2
3"use client";
4
5import { useIntlayer } from "next-intlayer";
6
7export const ClientComponentExample = () => {
8  const content = useIntlayer("client-component-example"); // Créez la déclaration de contenu associée
9
10  return (
11    <div>
12      <h2>{content.title} </h2>
13      <p>{content.content}</p>
14    </div>
15  );
16};

tsx

1// src/components/ServerComponentExample.tsx
2
3import { useIntlayer } from "next-intlayer/server";
4
5export const ServerComponentExample = () => {
6  const content = useIntlayer("server-component-example"); // Créez la déclaration de contenu associée
7
8  return (
9    <div>
10      <h2>{content.title} </h2>
11      <p>{content.content}</p>
12    </div>
13  );
14};

Remarque : 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 :
tsx
1<img src={content.image.src.value} alt={content.image.value} />

Pour un usage plus détaillé d'intlayer dans le Client ou le composant Serveur, consultez l'exemple Next.js ici.

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

typescript

1// src/app/[locale]/layout.tsx ou src/app/[locale]/page.tsx
2
3import {
4  type IConfigLocales,
5  getTranslationContent,
6  getMultilingualUrls,
7} from "intlayer";
8import type { Metadata } from "next";
9import type { LocalParams } from "next-intlayer";
10
11export const generateMetadata = ({
12  params: { locale },
13}: LocalParams): Metadata => {
14  const t = <T>(content: IConfigLocales<T>) =>
15    getTranslationContent(content, locale);
16
17  /**
18   * Génère un objet contenant toutes les URL pour chaque locale.
19   *
20   * Exemple :
21   * ```ts
22   *  getMultilingualUrls('/about');
23   *
24   *  // Renvoie
25   *  // {
26   *  //   en: '/about',
27   *  //   fr: '/fr/about',
28   *  //   es: '/es/about',
29   *  // }
30   * ```
31   */
32  const multilingualUrls = getMultilingualUrls("/");
33
34  return {
35    title: t<string>({
36      en: "My title",
37      fr: "Mon titre",
38      es: "Mi título",
39    }),
40    description: t({
41      en: "My description",
42      fr: "Ma description",
43      es: "Mi descripción",
44    }),
45    alternates: {
46      canonical: url,
47      languages: { ...multilingualUrls, "x-default": "/" },
48    },
49    openGraph: {
50      url: multilingualUrls[locale],
51    },
52  };
53};
54
55// ... Reste 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 URL multilingues pour votre sitemap.

tsx

1// src/app/sitemap.ts
2
3import { getMultilingualUrls } from "intlayer";
4import type { MetadataRoute } from "next";
5
6const sitemap = (): MetadataRoute.Sitemap => [
7  {
8    url: "https://example.com",
9    alternates: {
10      languages: getMultilingualUrls("https://example.com"),
11    },
12  },
13  {
14    url: "https://example.com/login",
15    alternates: {
16      languages: getMultilingualUrls("https://example.com/login"),
17    },
18  },
19  {
20    url: "https://example.com/register",
21    alternates: {
22      languages: getMultilingualUrls("https://example.com/register"),
23    },
24  },
25];
26
27export default sitemap;

tsx

1// src/app/robots.ts
2import type { MetadataRoute } from "next";
3import { getMultilingualUrls } from "intlayer";
4
5const getAllMultilingualUrls = (urls: string[]) =>
6  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
7
8const robots = (): MetadataRoute.Robots => ({
9  rules: {
10    userAgent: "*",
11    allow: ["/"],
12    disallow: getAllMultilingualUrls(["/login", "/register"]),
13  },
14  host: "https://example.com",
15  sitemap: `https://example.com/sitemap.xml`,
16});
17
18export default robots;

En savoir plus sur l'optimisation du sitemap dans la documentation officielle de Next.js. En savoir plus sur l'optimisation du 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, vous pouvez utiliser la fonction setLocale fournie par le hook useLocale. Cette fonction vous permet de définir la locale de l'application et de mettre à jour le contenu en conséquence.

tsx

1import { Locales } from "intlayer";
2import { useLocale } from "next-intlayer";
3
4const MyComponent = () => {
5  const { setLocale } = useLocale();
6
7  return (
8    <button onClick={() => setLocale(Locales.French)}>Changer de langue</button>
9  );
10};

Configurer TypeScript

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

alt text

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

json5

1// tsconfig.json
2
3{
4  // votre configuration personnalisée
5  include: [
6    "src",
7    "types", // <- Incluez les types auto-générés
8  ],
9}

Configuration Git

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

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

gitignore

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

Si vous avez une idée d’amélioration pour améliorer cette documentation, n’hésitez pas à contribuer en submitant une pull request sur GitHub.

Lien GitHub de la documentation

Fonction Fetching Next.js 14 et App Router

Commencer à internationaliser (i18n) avec Intlayer et Next.js 15 App Router

Qu'est-ce qu'Intlayer ?

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

Étape 1 : Installer les dépendances

Étape 2 : Configurer votre projet

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

Étape 4 : Configurer le middleware pour la détection de locale

Étape 5 : Définir des routes dynamiques pour les locales

Étape 6 : Déclarer votre contenu

Étape 7 : Utiliser le contenu dans votre code

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

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

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

Configurer TypeScript

Configuration Git

Dans cette page