Documentation

Environnement

Intlayer avec Next.js

Next.js et Page Router

Commencer l'internationalisation (i18n) avec Intlayer et Next.js en utilisant le Page Router

Qu'est-ce qu'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, y compris son traditionnel Page Router.

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.
Assurer le support TypeScript avec des types générés automatiquement, améliorant l'auto-complétion et la détection des erreurs.
Bénéficier de fonctionnalités avancées, telles que la détection et le changement dynamiques de la langue.

Remarque : Intlayer est compatible avec Next.js 12, 13, 14 et 15. Si vous utilisez le Next.js App Router, référez-vous au guide du App Router. Pour Next.js 15, suivez ce guide.

Guide étape par étape pour installer Intlayer dans une application Next.js utilisant le Page Router

Étape 1 : Installer les dépendances

Installez les packages nécessaires en utilisant votre gestionnaire de paquets préféré :

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 définir les langues prises en charge par 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      // Ajoutez vos autres langues ici
12    ],
13    defaultLocale: Locales.ENGLISH,
14  },
15};
16
17export default config;

Pour une liste complète des options de configuration disponibles, référez-vous à la documentation de configuration.

Étape 3 : Intégrer Intlayer avec la configuration Next.js

Modifiez votre configuration Next.js pour incorporer Intlayer :

typescript

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

Étape 4 : Configurer le Middleware pour la Détection de Langue

Mettez en place un middleware pour détecter automatiquement et gérer la langue 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 de Langue Dynamiques

Implémentez le routage dynamique pour servir du contenu localisé en fonction de la langue de l'utilisateur.

Créer des pages spécifiques à la langue :
Renommez votre fichier de page principal pour inclure le segment dynamique [locale].
bash
1mv src/pages/index.tsx src/pages/[locale]/index.tsx
Mettre à jour _app.tsx pour gérer la localisation :
Modifiez votre _app.tsx pour inclure les fournisseurs Intlayer.
tsx
1// src/pages/_app.tsx 2 3import { AppProps } from "next/app"; 4import { IntlayerClientProvider } from "next-intlayer"; 5import { IntlayerServerProvider } from "next-intlayer/server"; 6import intlayerConfig from "../../intlayer.config"; 7 8function MyApp({ Component, pageProps }: AppProps) { 9 const { locale } = pageProps; 10 11 return ( 12 <IntlayerClientProvider locale={locale}> 13 <Component {...pageProps} /> 14 </IntlayerClientProvider> 15 ); 16} 17 18export default MyApp;
Configurer getStaticPaths et getStaticProps :
Dans votre [locale]/index.tsx, définissez les chemins et les propriétés pour gérer différentes langues.
tsx
1// src/pages/[locale]/index.tsx 2 3import { GetStaticPaths, GetStaticProps } from "next"; 4import { useIntlayer } from "next-intlayer"; 5import { Locales } from "intlayer"; 6 7const HomePage = () => { 8 return <div>{/* Votre contenu ici */}</div>; 9}; 10 11export const getStaticPaths: GetStaticPaths = async () => { 12 const locales = [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH]; // Ajoutez vos langues ici 13 14 const paths = locales.map((locale) => ({ 15 params: { locale }, 16 })); 17 18 return { paths, fallback: false }; 19}; 20 21export const getStaticProps: GetStaticProps = async ({ params }) => { 22 const locale = params?.locale as string; 23 24 return { 25 props: { 26 locale, 27 }, 28 }; 29}; 30 31export default HomePage;

Étape 6 : Déclarer Votre Contenu

Créez et gérez vos dictionnaires de contenu pour stocker les traductions.

tsx

1// src/pages/[locale]/home.content.ts
2import { t, type DeclarationContent } from "intlayer";
3
4const homeContent = {
5  key: "home",
6  content: {
7    title: t({
8      en: "Welcome to My Website",
9      fr: "Bienvenue sur mon site Web",
10      es: "Bienvenido a mi sitio web",
11    }),
12    description: t({
13      en: "Get started by editing this page.",
14      fr: "Commencez par éditer cette page.",
15      es: "Comience por editar esta página.",
16    }),
17  },
18} satisfies DeclarationContent;
19
20export default homeContent;

Pour plus d'informations sur la déclaration de contenu, référez-vous au guide sur la déclaration de contenu.

Étape 7 : Utiliser le Contenu dans Votre Code

Accédez à vos dictionnaires de contenu tout au long de votre application pour afficher le contenu traduit.

tsx

1// src/pages/[locale]/index.tsx
2
3import { GetStaticPaths, GetStaticProps } from "next";
4import { useIntlayer } from "next-intlayer";
5import { Locales } from "intlayer";
6import { ComponentExample } from "@component/ComponentExample";
7
8const HomePage = () => {
9  const content = useIntlayer("home");
10
11  return (
12    <div>
13      <h1>{content.title}</h1>
14      <p>{content.description}</p>
15      <ComponentExample />
16      {/* Composants supplémentaires */}
17    </div>
18  );
19};
20
21// ... Reste du code, y compris getStaticPaths et getStaticProps
22
23export default HomePage;

tsx

1// src/components/ComponentExample.tsx
2
3import { useIntlayer } from "next-intlayer";
4
5export const ComponentExample = () => {
6  const content = useIntlayer("client-component-example"); // Assurez-vous d'avoir une déclaration de contenu correspondante
7
8  return (
9    <div>
10      <h2>{content.title}</h2>
11      <p>{content.content}</p>
12    </div>
13  );
14};

Remarque : Lorsque vous utilisez des traductions dans des attributs de string (ex. alt, title, href, aria-label), appelez la valeur de la fonction comme suit :

tsx

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

(Facultatif) Étape 8 : Internationaliser Vos Métadonnées

Pour internationaliser les métadonnées telles que les titres et descriptions de page, utilisez la fonction getStaticProps en conjonction avec la fonction getTranslationContent d'Intlayer.

tsx

1// src/pages/[locale]/index.tsx
2
3import { GetStaticPaths, GetStaticProps } from "next";
4import { type IConfigLocales, getTranslationContent, Locales } from "intlayer";
5import { useIntlayer } from "next-intlayer";
6
7interface HomePageProps {
8  locale: string;
9  metadata: Metadata;
10}
11
12const HomePage = ({ metadata }: HomePageProps) => {
13  // Les métadonnées peuvent être utilisées dans le head ou d'autres composants selon les besoins
14  return (
15    <div>
16      <Head>
17        <title>{metadata.title}</title>
18        <meta name="description" content={metadata.description} />
19      </Head>
20
21      {/* Contenu supplémentaire */}
22    </div>
23  );
24};
25
26export const getStaticProps: GetStaticProps = async ({ params }) => {
27  const locale = params?.locale as string;
28
29  const t = <T,>(content: IConfigLocales<T>) =>
30    getTranslationContent(content, locale);
31
32  const metadata = {
33    title: t({
34      en: "My Website",
35      fr: "Mon Site Web",
36      es: "Mi Sitio Web",
37    }),
38    description: t({
39      en: "Welcome to my website.",
40      fr: "Bienvenue sur mon site Web.",
41      es: "Bienvenido a mi sitio web.",
42    }),
43  };
44
45  return {
46    props: {
47      locale,
48      metadata,
49    },
50  };
51};
52
53export default HomePage;
54
55// ... Reste du code y compris getStaticPaths

(Facultatif) Étape 9 : Changer la Langue de Votre Contenu

Pour permettre aux utilisateurs de changer de langue dynamiquement, utilisez la fonction setLocale fournie par le hook useLocale.

tsx

1// src/components/LanguageSwitcher.tsx
2
3import { Locales } from "intlayer";
4import { useLocalePageRouter } from "next-intlayer";
5
6const LanguageSwitcher = () => {
7  const { setLocale } = useLocalePageRouter();
8
9  return (
10    <div>
11      <button onClick={() => setLocale(Locales.ENGLISH)}>English</button>
12      <button onClick={() => setLocale(Locales.FRENCH)}>Français</button>
13      <button onClick={() => setLocale(Locales.SPANISH)}>Español</button>
14      {/* Ajoutez plus de boutons pour d'autres langues */}
15    </div>
16  );
17};
18
19export default LanguageSwitcher;

Configurer TypeScript

Intlayer utilise l'augmentation de module pour améliorer les capacités de TypeScript, offrant une meilleure sécurité de type et auto-complétion.

Assurez-vous que TypeScript inclut les types générés automatiquement :
Mettez à jour votre tsconfig.json pour inclure les types générés automatiquement.
json
1// tsconfig.json 2 3{ 4 "compilerOptions": { 5 // Vos configurations TypeScript existantes 6 }, 7 "include": [ 8 "src", 9 "types" // Incluez les types auto-générés 10 ] 11}
Exemple des avantages de TypeScript :

Configuration de Git

Pour garder votre dépôt propre et éviter de commettre des fichiers générés, il est recommandé d'ignorer les fichiers créés par Intlayer.

Mettre à jour .gitignore :
Ajoutez les lignes suivantes à votre fichier .gitignore :
gitignore
1# Ignorer les fichiers générés par Intlayer 2.intlayer

Ressources supplémentaires

Documentation Intlayer : Dépôt GitHub
Guide de déclaration de contenu : Déclaration de Contenu
Documentation de configuration : Guide de Configuration

En suivant ce guide, vous pouvez intégrer efficacement Intlayer dans votre application Next.js en utilisant le Page Router, permettant un support d'internationalisation robuste et évolutif pour vos projets web.

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

Next.js 14 et App Router Intlayer avec React CRA

Commencer l'internationalisation (i18n) avec Intlayer et Next.js en utilisant le Page Router

Qu'est-ce qu'Intlayer ?

Guide étape par étape pour installer Intlayer dans une application Next.js utilisant le Page Router

Étape 1 : Installer les dépendances

Étape 2 : Configurer votre projet

Étape 3 : Intégrer Intlayer avec la configuration Next.js

Étape 4 : Configurer le Middleware pour la Détection de Langue

Étape 5 : Définir des Routes de Langue Dynamiques

Étape 6 : Déclarer Votre Contenu

Étape 7 : Utiliser le Contenu dans Votre Code

(Facultatif) Étape 8 : Internationaliser Vos Métadonnées

(Facultatif) Étape 9 : Changer la Langue de Votre Contenu

Configurer TypeScript

Configuration de Git

Ressources supplémentaires

Dans cette page