Traduire votre React Router v7 avec Intlayer | Internationalisation (i18n)

Ce guide montre comment intégrer Intlayer pour une internationalisation fluide dans les projets React Router v7 avec un routage sensible à la locale, la prise en charge de TypeScript, et des pratiques de développement modernes.

Ce guide se concentre sur le routage frontend. Pour le routage fs-routes, consultez le guide Intlayer avec React Router v7 File-System Routes.

Table of Contents

Pourquoi Intlayer plutôt que des alternatives ?

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

Guide étape par étape pour configurer Intlayer dans une application React Router v7 avec des routes basées sur le système de fichiers

VidéoCode (basé sur la configuration)Code (routes basées sur le système de fichiers)Démo (basée sur la configuration)

www.youtube.com

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

intlayer-react-router-v7.vercel.app

Open embedded page in fullscreen

See Application Template on GitHub.

1. 1

   Installer les dépendances

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

   bash

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   npx intlayer init --interactive
   

   le flag --interactive est optionnel. Utilisez intlayer-cli init si vous êtes un agent IA.

   Cette commande détectera votre environnement et installera les packages requis. Par exemple :

   bash

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   npm install intlayer react-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

   Le package core 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.

   • react-intlayer Le package qui intègre Intlayer avec les applications React. Il fournit des context providers et des hooks pour l'internationalisation React.

   • vite-intlayer Inclut le plugin Vite pour intégrer Intlayer avec le bundler Vite, ainsi que des middleware pour détecter la locale préférée de l'utilisateur, gérer les cookies et gérer la redirection d'URL.

2. 2

   Configuration de votre projet

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

   intlayer.config.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { type IntlayerConfig, Locales } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       defaultLocale: Locales.ENGLISH,
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
     },
   };
   
   export default config;
   

   Grâce à ce fichier de configuration, vous pouvez configurer les URLs localisées, la redirection via middleware, les noms des 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. 3

   Intégrer Intlayer dans votre configuration Vite

   Ajoutez le plugin intlayer dans votre configuration :

   vite.config.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { reactRouter } from "@react-router/dev/vite";
   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [reactRouter(), intlayer()],
   });
   

   Le plugin Vite intlayer() est utilisé pour intégrer Intlayer avec Vite. 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 Intlayer au sein de l'application Vite. De plus, il fournit des alias pour optimiser les performances.

4. 4

   Configurer les routes de React Router v7

   Routage basé sur la configurationRoutes basées sur le système de fichiers

   Configurez votre routage avec des routes sensibles à la locale :

   app/routes.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { layout, route, type RouteConfig } from "@react-router/dev/routes";
   
   export default [
     route("/:lang?", "routes/page.tsx"), // Page d'accueil localisée
     route("/:lang?/about", "routes/about/page.tsx"), // Page À propos localisée
   ] satisfies RouteConfig;
   

   Configurez votre configuration de routage pour utiliser des routes basées sur le système de fichiers avec flatRoutes :

   app/routes.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import type { RouteConfig } from "@react-router/dev/routes";
   import { flatRoutes } from "@react-router/fs-routes";
   import { configuration } from "intlayer";
   
   const routes: RouteConfig = flatRoutes({
     // Ignorer les fichiers de déclaration de contenu d'être traités comme des routes
     ignoredRouteFiles: configuration.content.fileExtensions.map(
       (fileExtension) => `**/*${fileExtension}`
     ),
   });
   
   export default routes;
   

   La fonction flatRoutes de @react-router/fs-routes active le routage basé sur le système de fichiers, où la structure des fichiers dans le répertoire routes/ détermine les routes de votre application. L'option ignoredRouteFiles garantit que les fichiers de déclaration de contenu Intlayer (.content.ts, etc.) ne sont pas traités comme des fichiers de route.

5. 5

   Créer les composants de mise en page

   Configurez votre mise en page racine et vos mises en page spécifiques à la locale :

   Mise en page racine

   app/root.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { getLocaleFromPath } from "intlayer";
   import { IntlayerProvider } from "react-intlayer";
   import {
     data,
     Meta,
     Scripts,
     ScrollRestoration,
     useLoaderData,
   } from "react-router";
   import type { Route } from "./+types/root";
   
   // ... Unchanged App, links and ErrorBoundary code
   
   export async function loader({ request }: Route.LoaderArgs) {
     const locale = getLocaleFromPath(request.url);
   
     if (!locale) {
       throw data("Language not supported", { status: 404 });
     }
   
     return { locale };
   }
   
   export function Layout({
     children,
   }: { children: React.ReactNode } & Route.ComponentProps) {
     const data = useLoaderData<typeof loader>();
     const { locale } = data ?? {};
   
     return (
       <html lang={locale}>
         <head>
           <meta charSet="utf-8" />
           <meta content="width=device-width, initial-scale=1" name="viewport" />
           <Meta />
           <Links />
         </head>
         <body>
           <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
           <ScrollRestoration />
           <Scripts />
         </body>
       </html>
     );
   }
   

6. 6

   Déclarez votre contenu

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

   app/routes/page.content.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { t, type Dictionary } from "intlayer";
   
   const pageContent = {
     key: "page",
     content: {
       title: t({
         en: "Welcome to React Router v7 + Intlayer",
         es: "Bienvenido a React Router v7 + Intlayer",
         fr: "Bienvenue sur React Router v7 + Intlayer",
       }),
       description: t({
         en: "Build multilingual applications with ease using React Router v7 and Intlayer.",
         es: "Cree aplicaciones multilingües fácilmente usando React Router v7 y Intlayer.",
         fr: "Créez des applications multilingues facilement avec React Router v7 et Intlayer.",
       }),
       aboutLink: t({
         en: "Learn About Us",
         es: "Aprender Sobre Nosotros",
         fr: "En savoir plus sur nous",
       }),
       homeLink: t({
         en: "Home",
         es: "Inicio",
         fr: "Accueil",
       }),
     },
   } 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, ./app). Et correspondent à l'extension des fichiers de déclaration de contenu (par défaut, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

   Pourrait être placé dans app/routes/($locale)._index.content.ts en cas d'utilisation du routage basé sur le système de fichiers.

   Pour plus de détails, référez-vous à la documentation sur la déclaration de contenu.

7. 7

   Créez des composants sensibles à la locale

   Créez un composant LocalizedLink pour la navigation sensible à la locale :

   app/components/localized-link.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import type { FC } from "react";
   
   import { getLocalizedUrl, type LocalesValues } from "intlayer";
   import { useLocale } from "react-intlayer";
   import { Link, type LinkProps, type To } from "react-router";
   
   const isExternalLink = (to: string) => /^(https?:)?\/\//.test(to);
   
   // Vérifie si le lien est externe
   export const locacalizeTo = (to: To, locale: LocalesValues): To => {
     if (typeof to === "string") {
       if (isExternalLink(to)) {
         return to;
       }
   
       return getLocalizedUrl(to, locale);
     }
   
     if (isExternalLink(to.pathname ?? "")) {
       return to;
     }
   
     return {
       ...to,
       pathname: getLocalizedUrl(to.pathname ?? "", locale),
     };
   };
   
   // Composant LocalizedLink pour la navigation locale
   export const LocalizedLink: FC<LinkProps> = (props) => {
     const { locale } = useLocale();
   
     return <Link {...props} to={locacalizeTo(props.to, locale)} />;
   };
   

   Dans le cas où vous souhaitez naviguer vers les routes localisées, vous pouvez utiliser le hook useLocalizedNavigate :

   app/hooks/useLocalizedNavigate.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { useLocale } from "react-intlayer";
   import { type NavigateOptions, type To, useNavigate } from "react-router";
   
   import { locacalizeTo } from "~/components/localized-link";
   
   export const useLocalizedNavigate = () => {
     const navigate = useNavigate();
     const { locale } = useLocale();
   
     const localizedNavigate = (to: To, options?: NavigateOptions) => {
       const localedTo = locacalizeTo(to, locale);
   
       navigate(localedTo, options);
     };
   
     return localizedNavigate;
   };
   

8. 8

   Utilisez Intlayer dans vos pages

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

   Page d'accueil localisée

   Routage basé sur la configurationRoutes basées sur le système de fichiers

   app/routes/page.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { getIntlayer, validatePrefix } from "intlayer";
   import { useIntlayer } from "react-intlayer";
   import { data } from "react-router";
   
   import { LocaleSwitcher } from "~/components/locale-switcher";
   
   import { Navbar } from "~/components/navbar";
   import type { Route } from "./+types/page";
   
   export const loader = ({ params }: Route.LoaderArgs) => {
     const { locale } = params;
   
     const { isValid } = validatePrefix(locale);
   
     if (!isValid) {
       throw data("Locale not supported", { status: 404 });
     }
   };
   
   export const meta: Route.MetaFunction = ({ params }) => {
     const content = getIntlayer("page", params.locale);
   
     return [
       { title: content.title },
       { content: content.description, name: "description" },
     ];
   };
   
   export default function Page() {
     const { title, description, aboutLink } = useIntlayer("page");
   
     return (
       <div>
         <h1>{title}</h1>
         <p>{description}</p>
         <nav>
           <LocalizedLink to="/about">{aboutLink}</LocalizedLink>
         </nav>
       </div>
     );
   }
   

   app/routes/($locale)._index.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { getIntlayer, validatePrefix } from "intlayer";
   import { useIntlayer } from "react-intlayer";
   import { data } from "react-router";
   
   import { LocaleSwitcher } from "~/components/locale-switcher";
   
   import { Navbar } from "~/components/navbar";
   import type { Route } from "./+types/($locale)._index";
   
   export const loader = ({ params }: Route.LoaderArgs) => {
     const { locale } = params;
   
     const { isValid } = validatePrefix(locale);
   
     if (!isValid) {
       throw data("Locale not supported", { status: 404 });
     }
   };
   
   export const meta: Route.MetaFunction = ({ params }) => {
     const content = getIntlayer("page", params.locale);
   
     return [
       { title: content.title },
       { content: content.description, name: "description" },
     ];
   };
   
   export default function Page() {
     const { title, description, aboutLink } = useIntlayer("page");
   
     return (
       <div>
         <h1>{title}</h1>
         <p>{description}</p>
         <nav>
           <LocalizedLink to="/about">{aboutLink}</LocalizedLink>
         </nav>
       </div>
     );
   }
   

   Pour en savoir plus sur le hook useIntlayer, consultez la documentation.

   Si votre application existe déjà, vous pouvez utiliser le Compilateur Intlayer, ainsi que la commande d'extraction, pour transformer des milliers de composants en une seconde.

9. 9

   Créer un composant de changement de langue

   Créez un composant pour permettre aux utilisateurs de changer de langue :

   Routage basé sur la configurationRoutes basées sur le système de fichiers

   app/components/locale-switcher.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import type { FC } from "react";
   
   import {
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
     getPathWithoutLocale,
     Locales,
   } from "intlayer";
   import { setLocaleInStorage, useIntlayer, useLocale } from "react-intlayer";
   import { Link, useLocation } from "react-router";
   
   export const LocaleSwitcher: FC = () => {
     const { localeSwitcherLabel } = useIntlayer("locale-switcher");
     const { pathname } = useLocation();
   
     const { availableLocales, locale } = useLocale();
   
     const pathWithoutLocale = getPathWithoutLocale(pathname);
   
     return (
       <ol>
         {availableLocales.map((localeItem) => (
           <li key={localeItem}>
             <Link
               aria-current={localeItem === locale ? "page" : undefined}
               aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`}
               onClick={() => setLocale(localeItem)}
               to={getLocalizedUrl(pathWithoutLocale, localeItem)}
             >
               <span>
                 {/* Locale - par exemple FR */}
                 {localeItem}
               </span>
               <span>
                 {/* Langue dans sa propre locale - par exemple Français */}
                 {getLocaleName(localeItem, locale)}
               </span>
               <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                 {/* Langue dans la locale actuelle - par exemple Francés avec la locale actuelle définie sur Locales.SPANISH */}
                 {getLocaleName(localeItem)}
               </span>
               <span dir="ltr" lang={Locales.ENGLISH}>
                 {/* Langue en anglais - par exemple French */}
                 {getLocaleName(localeItem, Locales.ENGLISH)}
               </span>
             </Link>
           </li>
         ))}
       </ol>
     );
   };
   

   app/components/locale-switcher.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import type { FC } from "react";
   
   import {
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
     getPathWithoutLocale,
     defaultLocale,
   } from "intlayer";
   import { useIntlayer, useLocale } from "react-intlayer";
   import { Link, useLocation } from "react-router";
   
   export const LocaleSwitcher: FC = () => {
     const { localeSwitcherLabel } = useIntlayer("locale-switcher");
     const { pathname } = useLocation();
   
     const { availableLocales, locale, setLocale } = useLocale();
   
     const pathWithoutLocale = getPathWithoutLocale(pathname);
   
     return (
       <ol>
         {availableLocales.map((localeItem) => (
           <li key={localeItem}>
             <Link
               aria-current={localeItem === locale ? "page" : undefined}
               aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`}
               onClick={() => setLocale(localeItem)}
               reloadDocument // Recharger la page pour appliquer la nouvelle locale
               to={getLocalizedUrl(pathWithoutLocale, 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 actuelle - ex. Francés avec la locale actuelle définie sur Locales.SPANISH */}
                 {getLocaleName(localeItem)}
               </span>
               <span dir="ltr" lang={defaultLocale}>
                 {/* Langue en anglais - ex. French */}
                 {getLocaleName(localeItem, defaultLocale)}
               </span>
             </Link>
           </li>
         ))}
       </ol>
     );
   };
   

   Pour en savoir plus sur le hook useLocale, consultez la documentation.

10. 10

    Ajouter la gestion des attributs HTML

    Créez un hook pour gérer les attributs lang et dir du HTML :

    app/hooks/useI18nHTMLAttributes.tsx

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { getHTMLTextDir } from "intlayer";
    import { useEffect } from "react";
    import { useLocale } from "react-intlayer";
    
    export const useI18nHTMLAttributes = () => {
      const { locale } = useLocale();
    
      useEffect(() => {
        document.documentElement.lang = locale;
        document.documentElement.dir = getHTMLTextDir(locale);
      }, [locale]);
    };
    

    Puis utilisez-le dans votre composant racine :

    app/routes/layout.tsx

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { Outlet } from "react-router";
    import { IntlayerProvider } from "react-intlayer";
    
    import { useI18nHTMLAttributes } from "app/hooks/useI18nHTMLAttributes"; // importer le hook
    
    export default function RootLayout() {
      useI18nHTMLAttributes(); // appeler le hook
    
      return (
        <IntlayerProvider>
          <Outlet />
        </IntlayerProvider>
      );
    }
    

11. 11

    Ajouter un middleware

    Vous pouvez également utiliser intlayerProxy pour ajouter un routage côté serveur à votre application. Ce plugin détectera automatiquement la locale actuelle en fonction de l'URL et définira le cookie de locale approprié. Si aucune locale n'est spécifiée, le plugin déterminera la locale la plus appropriée en fonction des préférences linguistiques du navigateur de l'utilisateur. Si aucune locale n'est détectée, il redirigera vers la locale par défaut.

    Notez que pour utiliser intlayerProxy en production, vous devez basculer le package vite-intlayer de devDependencies à dependencies.

    Depuis Intlayer v9, intlayerProxy() est intégré directement dans le plugin intlayer() et activé par défaut via l'option routing.enableProxy (true par défaut). L'enregistrement séparé comme montré ci-dessous est désormais facultatif — il est conservé pour la compatibilité rétroactive et pour les configurations qui doivent contrôler l'ordre des plugins. Définissez routing.enableProxy: false pour refuser. Voir les notes de version v9.

    vite.config.ts

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { defineConfig } from "vite";
    import react from "@vitejs/plugin-react-swc";
    import { intlayer } from "vite-intlayer";
    
    // https://vitejs.dev/config/
    export default defineConfig({
      plugins: [
        react(),
        intlayer({
          proxy: {
            ignore: (req) => req.url?.startsWith("/api"),
          },
        }),
      ],
    });
    

12. 12

    Extraire le contenu de vos composants

    Facultatif

    Si vous avez une base de code existante, transformer des milliers de fichiers peut prendre beaucoup de temps.

    Pour faciliter ce processus, Intlayer propose un compilateur / extracteur pour transformer vos composants et extraire le contenu.

    Pour le configurer, vous pouvez ajouter une section compiler dans votre fichier intlayer.config.ts :

    intlayer.config.ts

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... Reste de votre configuration
      compiler: {
        /**
         * Indique si le compilateur doit être activé.
         */
        enabled: true,
    
        /**
         * Définit le chemin des fichiers de sortie
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * Indique si les composants doivent être sauvegardés après avoir été transformés.
         * De cette façon, le compilateur peut être exécuté une seule fois pour transformer l'application, puis il peut être supprimé.
         */
        saveComponents: false,
    
        /**
         * Préfixe de clé de dictionnaire
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    Commande dCompilateur Babel

    Exécutez l'extracteur pour transformer vos composants et extraire le contenu

    bash

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    npx intlayer extract
    

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    Mettez à jour votre fichier vite.config.ts pour inclure le plugin intlayerCompiler :

    vite.config.ts

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // Adds the compiler plugin
      ],
    });
    

    bash

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    npm run build # Ou npm run dev
    

Configure TypeScript

Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.

Ensure your TypeScript configuration includes the autogenerated types:

{
  // ... your existing configurations
  include: [
    // ... your existing includes
    ".intlayer/**/*.ts", // Include the auto-generated types
  ],
}

Git Configuration

It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.

To do this, you can add the following instructions to your .gitignore file:

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

VS Code Extension

To improve your development experience with Intlayer, you can install the official Intlayer VS Code Extension.

Install from the VS Code Marketplace

This extension provides:

• Autocompletion for translation keys.
• Real-time error detection for missing translations.
• Inline previews of translated content.
• Quick actions to easily create and update translations.

For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.

Go Further

To go further, you can implement the visual editor or externalize your content using the CMS.

Références de la documentation

• Documentation Intlayer
• Documentation React Router v7
• Hook useIntlayer
• Hook useLocale
• Déclaration de contenu
• Configuration

Ce guide complet vous fournit tout ce dont vous avez besoin pour intégrer Intlayer avec React Router v7 afin d’obtenir une application entièrement internationalisée avec un routage sensible à la locale et une prise en charge de TypeScript.

Questions fréquentes