Getting Started internationalizing (i18n) with Intlayer and Next.js 14 with App Router
What is Intlayer?
Intlayer est une bibliothèque d'internationalisation (i18n) open-source innovante, conçue pour simplifier le support multilingue dans les applications web modernes. Intlayer s'intègre parfaitement avec le dernier framework Next.js 14, 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 (à partir de Next.js >= 15).
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'auto-complétion et la détection d'erreurs.
- Bénéficier de fonctionnalités avancées, comme la détection et le changement dynamique de locale.
Note : 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 15 avec ou sans turbopack, référez-vous à ce guide.
Step-by-Step Guide to Set Up Intlayer in a Next.js Application
Step 1: Install Dependencies
Installez les packages nécessaires en utilisant npm :
1npm install intlayer next-intlayer1yarn add intlayer next-intlayer1pnpm add intlayer next-intlayerStep 2: Configure Your Project
Créez un fichier de configuration pour configurer les langues de votre application :
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.
Step 3: Integrate Intlayer in Your Next.js Configuration
Configurez votre installation Next.js pour utiliser Intlayer :
1// next.config.mjs
2import { withIntlayer } from "next-intlayer/server";
3
4/** @type {import('next').NextConfig} */
5const nextConfig = {};
6
7export default withIntlayer(nextConfig);Step 4: Configure Middleware for Locale Detection
Configurez un middleware pour détecter la locale préférée de l'utilisateur :
1// src/middleware.ts
2export { intlayerMiddleware as middleware } from "next-intlayer/middleware";
3
4export const config = {
5 matcher: "/((?!api|static|.*\\..*|_next).*)",
6};Step 5: Define Dynamic Locale Routes
Implémentez un routage dynamique pour le 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.
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;Ensuite, ajoutez une nouvelle mise en page dans votre répertoire [locale] :
1// src/app/[locale]/layout.tsx
2
3import { type Next14LayoutIntlayer } from "next-intlayer";
4import { Inter } from "next/font/google";
5import { getHTMLTextDir } from "intlayer";
6
7const inter = Inter({ subsets: ["latin"] });
8
9const LocaleLayout: Next14LayoutIntlayer = ({
10 children,
11 params: { locale },
12}) => (
13 <html lang={locale} dir={getHTMLTextDir(locale)}>
14 <body className={inter.className}>{children}</body>
15 </html>
16);
17
18export default LocaleLayout;Step 6: Declare Your Content
Créez et gérez vos dictionnaires de contenu :
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.
Step 7: Utilize Content in Your Code
Accédez à vos dictionnaires de contenu tout au long de votre application :
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 Next14PageIntlayer, IntlayerClientProvider } from "next-intlayer";
8import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
9
10const Page: Next14PageIntlayer = ({ params: { locale } }) => {
11 const content = useIntlayer("page", locale);
12
13 return (
14 <>
15 <p>
16 {content.getStarted.main}
17 <code>{content.getStarted.pageLink}</code>
18 </p>
19 {/**
20 * IntlayerServerProvider est utilisé pour fournir la locale aux enfants du serveur
21 * N'est pas fonctionnel s'il est défini dans la mise en page
22 */}
23 <IntlayerServerProvider locale={locale}>
24 <ServerComponentExample />
25 </IntlayerServerProvider>
26 {/**
27 * IntlayerClientProvider est utilisé pour fournir la locale aux enfants du client
28 * Peut être défini dans n'importe quel composant parent, y compris la mise en page
29 */}
30 <IntlayerClientProvider locale={locale}>
31 <ClientComponentExample />
32 </IntlayerClientProvider>
33 </>
34 );
35};
36
37export default Page;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éer une 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};1// src/components/ServerComponentExample.tsx
2
3import { useIntlayer } from "next-intlayer/server";
4
5export const ServerComponentExample = () => {
6 const content = useIntlayer("server-component-example"); // Créer une 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};Note : 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 :
tsx1<img src={content.image.src.value} alt={content.image.value} />
Pour une utilisation plus détaillée de Intlayer dans le composant Client ou Serveur, consultez l'exemple Next.js ici.
(Optional) Step 8: Internationalization of your metadata
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.
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 * // Retourne
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 codeDécouvrez l'optimisation des métadonnées dans la documentation officielle de Next.js.
(Optional) Step 9: Internationalization of your sitemap.xml and 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.
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;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 de robots.txt dans la documentation officielle de Next.js.
(Optional) Step 10: Change the language of your content
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.
1import { Locales } from "intlayer";
2import { useLocale } from "next-intlayer";
3
4const MyComponent = () => {
5 const { setLocale } = useLocale();
6
7 return (
8 <button onClick={() => setLocale(Locales.English)}>
9 Changer de langue
10 </button>
11 );
12};Configure TypeScript
Intlayer utilise l'augmentation de module pour tirer parti de TypeScript et renforcer votre codebase.
Assurez-vous que votre configuration TypeScript inclut les types générés automatiquement.
1// tsconfig.json
2
3{
4 // votre configuration personnalisée
5 include: [
6 "src",
7 "types", // <- Inclure les types générés automatiquement
8 ],
9}Git Configuration
Il est recommandé d'ignorer les fichiers générés par Intlayer. Cela vous permet d'éviter de les engager dans votre dépôt Git.
Pour ce faire, vous pouvez ajouter les instructions suivantes à votre fichier .gitignore :
1# Ignorer les fichiers générés par Intlayer
2.intlayerSi 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