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.

Qu'est-ce que 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.

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 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.
• Bénéficier de fonctionnalités avancées, comme la détection et le changement dynamique de la locale.
• Activer un routage sensible à la locale avec le système de routage basé sur la configuration de React Router v7.

Guide étape par étape pour configurer Intlayer dans une application React Router v7

Étape 1 : Installer les dépendances

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

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

• intlayer

• 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.

• react-intlayer Le package qui intègre Intlayer avec une application React. Il fournit des fournisseurs de contexte et des hooks pour l'internationalisation dans React.

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

Étape 2 : Configuration de votre projet

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

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.

Étape 3 : Intégrer Intlayer dans votre configuration Vite

Ajoutez le plugin intlayer dans votre configuration :

import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";import tsconfigPaths from "vite-tsconfig-paths";export default defineConfig({  plugins: [reactRouter(), tsconfigPaths(), 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.

Étape 4 : Configurer les routes de React Router v7

Configurez votre routage avec des routes sensibles à la locale :

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

Étape 5 : Créer les composants de mise en page

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

Mise en page racine

import { IntlayerProvider } from "react-intlayer";import { Outlet } from "react-router";import type { Route } from "./+types/layout";export default function RootLayout({ params }: Route.ComponentProps) {  const { locale } = params;  return (    <IntlayerProvider locale={locale}>      <Outlet />    </IntlayerProvider>  );}

Étape 6 : Déclarez votre contenu

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

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,mjx,cjs,cjx}).

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

Étape 7 : Créez des composants sensibles à la locale

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

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 externeexport 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 localeexport 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 :

import { useLocale } from "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;};

Étape 8 : Utilisez Intlayer dans vos pages

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

Page d'accueil localisée

import { useIntlayer } from "react-intlayer";import { LocalizedLink } from "~/components/localized-link";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.

Étape 9 : Créer un composant de changement de langue

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

import type { FC } from "react";import {  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,  getPathWithoutLocale,} from "intlayer";import { setLocaleCookie, 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={() => setLocaleCookie(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>  );};

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

Étape 10 : Ajouter la gestion des attributs HTML (optionnel)

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

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 :

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

Étape 11 : Ajouter un middleware (Optionnel)

Vous pouvez également utiliser le intlayerMiddleware 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 le intlayerMiddleware en production, vous devez déplacer le package vite-intlayer de devDependencies vers dependencies.

import { defineConfig } from "vite";import react from "@vitejs/plugin-react-swc";import { intlayer, intlayerMiddleware } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [react(), intlayer(), intlayerMiddleware()],});

Configurer TypeScript

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

Assurez-vous que votre configuration TypeScript inclut les types générés automatiquement :

{  // ... vos configurations existantes  include: [    // ... vos inclusions 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 commettre dans votre dépôt Git.

Pour ce faire, 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 pour VS Code.

Installer depuis le Marketplace VS Code

Cette extension offre :

• L’autocomplétion pour les clés de traduction.
• La détection d’erreurs en temps réel pour les traductions manquantes.
• Des aperçus en ligne du contenu traduit.
• Des 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 Intlayer pour VS Code.

Aller plus loin

Pour aller plus loin, vous pouvez implémenter l’éditeur visuel ou externaliser votre contenu en utilisant le 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.

Historique de la documentation