@intlayer/docs 5.8.1 → 6.0.0-canary.0

package/docs/fr/intlayer_with_react_router_v7.md

@@ -0,0 +1,549 @@
+---
+createdAt: 2025-09-04
+updatedAt: 2025-09-04
+title: Prise en main d'Intlayer avec React Router v7
+description: Apprenez comment ajouter l'internationalisation (i18n) à votre application React Router v7 en utilisant Intlayer. Suivez ce guide complet pour rendre votre application multilingue avec un routage sensible à la locale.
+keywords:
+  - Internationalisation
+  - Documentation
+  - Intlayer
+  - React Router v7
+  - React
+  - i18n
+  - TypeScript
+  - Routage par locale
+slugs:
+  - doc
+  - environment
+  - vite-and-react
+  - react-router-v7
+applicationTemplate: https://github.com/AydinTheFirst/react-router-intlayer
+author: AydinTheFirst
+---
+
+# Prise en main de l'internationalisation (i18n) avec Intlayer et React Router v7
+
+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 qu'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 des erreurs.
+- **Bénéficier de fonctionnalités avancées**, comme la détection et le changement dynamique de la locale.
+- **Activer le 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é :
+
+```bash packageManager="npm"
+npm install intlayer react-intlayer
+npm install vite-intlayer --save-dev
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer react-intlayer
+pnpm add vite-intlayer --save-dev
+```
+
+- **intlayer**
+
+- **intlayer**
+
+  Le paquet principal qui fournit des outils d'internationalisation pour la gestion de la configuration, la traduction, la [déclaration de contenu](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/dictionary/get_started.md), la transpilation, et les [commandes CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/intlayer_cli.md).
+
+- **react-intlayer**
+  Le paquet qui intègre Intlayer avec une application React. Il fournit des fournisseurs de contexte et des hooks pour l'internationalisation dans React.
+
+- **vite-intlayer**
+  Inclut le plugin Vite pour intégrer Intlayer avec le [bundler Vite](https://vite.dev/guide/why.html#why-bundle-for-production), ainsi qu'un middleware 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 :
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { type IntlayerConfig, Locales } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    defaultLocale: Locales.ENGLISH,
+    locales: [Locales.ENGLISH, Locales.TURKISH],
+  },
+  middleware: {
+    prefixDefault: true, // Toujours préfixer la locale par défaut dans les URLs
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    defaultLocale: Locales.ENGLISH,
+    locales: [Locales.ENGLISH, Locales.TURKISH],
+  },
+  middleware: {
+    prefixDefault: true,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    defaultLocale: Locales.ENGLISH,
+    locales: [Locales.ENGLISH, Locales.TURKISH],
+  },
+  middleware: {
+    prefixDefault: true,
+  },
+};
+
+module.exports = config;
+```
+
+> Grâce à ce fichier de configuration, vous pouvez configurer des 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/configuration.md).
+
+### Étape 3 : Configurer les routes de React Router v7
+
+Configurez votre routage avec des routes sensibles à la locale :
+
+```typescript fileName="app/routes.ts" codeFormat="typescript"
+import { layout, route, type RouteConfig } from "@react-router/dev/routes";
+
+export default [
+  layout("routes/layout.tsx", [
+    route("/", "routes/page.tsx"), // Page racine - redirige vers la locale
+    route("/:lang", "routes/[lang]/page.tsx"), // Page d'accueil localisée
+    route("/:lang/about", "routes/[lang]/about/page.tsx"), // Page "à propos" localisée
+  ]),
+] satisfies RouteConfig;
+```
+
+### Étape 4 : Intégrer Intlayer dans votre configuration Vite
+
+Ajoutez le plugin intlayer dans votre configuration :
+
+```typescript fileName="vite.config.ts" codeFormat="typescript"
+import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+import { intlayerMiddlewarePlugin, intlayerPlugin } from "vite-intlayer";
+import tsconfigPaths from "vite-tsconfig-paths";
+
+export default defineConfig({
+  plugins: [
+    reactRouter(),
+    tsconfigPaths(),
+    intlayerPlugin(),
+    intlayerMiddlewarePlugin(),
+  ],
+});
+```
+
+> Le plugin Vite `intlayerPlugin()` 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 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
+
+```tsx fileName="app/routes/layout.tsx" codeFormat="typescript"
+// app/routes/layout.tsx
+import { Outlet } from "react-router";
+import { IntlayerProvider } from "react-intlayer";
+
+export default function RootLayout() {
+  return (
+    <IntlayerProvider>
+      <Outlet />
+    </IntlayerProvider>
+  );
+}
+```
+
+### Étape 6 : Déclarez Votre Contenu
+
+Créez et gérez vos déclarations de contenu pour stocker les traductions :
+
+```tsx fileName="app/routes/[lang]/page.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const pageContent = {
+  key: "page",
+  content: {
+    title: t({
+      en: "Welcome to React Router v7 + Intlayer",
+      tr: "React Router v7 + Intlayer'a Hoş Geldiniz",
+    }),
+    description: t({
+      en: "Build multilingual applications with ease using React Router v7 and Intlayer.",
+tsx fileName="app/routes/[lang]/page.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const pageContent = {
+  key: "page",
+  content: {
+    title: t({
+      en: "Welcome to React Router v7 + Intlayer",
+      tr: "React Router v7 + Intlayer'a Hoş Geldiniz",
+      fr: "Bienvenue sur React Router v7 + Intlayer",
+    }),
+    description: t({
+      en: "Build multilingual applications with ease using React Router v7 and Intlayer.",
+      tr: "React Router v7 ve Intlayer kullanarak kolayca çok dilli uygulamalar geliştirin.",
+      fr: "Créez des applications multilingues facilement avec React Router v7 et Intlayer.",
+    }),
+    aboutLink: t({
+      en: "Learn About Us",
+      tr: "Hakkımızda Öğrenin",
+      fr: "En savoir plus sur nous",
+    }),
+    homeLink: t({
+      en: "Home",
+      tr: "Ana Sayfa",
+      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 de fichier de déclaration de contenu (par défaut, `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`).
+
+> Pour plus de détails, consultez la [documentation sur la déclaration de contenu](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/dictionary/get_started.md).
+
+### Étape 7 : Créez des composants sensibles à la locale
+
+Créez un composant `LocalizedLink` pour une navigation adaptée à la locale :
+
+```tsx fileName="app/components/localized-link.tsx" codeFormat="typescript"
+// app/components/localized-link.tsx
+import { getLocalizedUrl } from "intlayer";
+import { useLocale } from "react-intlayer";
+import React from "react";
+import { Link, useLocation } from "react-router";
+
+type RouterLinkProps = React.ComponentProps<typeof Link>;
+
+export default function LocalizedLink({ to, ...props }: RouterLinkProps) {
+  const { locale } = useLocale();
+  const location = useLocation();
+
+  const isExternal = (path: string) =>
+    /^([a-z][a-z0-9+.-]*:)?\/\//i.test(path) || path.startsWith("mailto:");
+
+  if (typeof to === "string") {
+    if (to.startsWith("/") && !isExternal(to)) {
+      return <Link to={getLocalizedUrl(to, locale)} {...props} />;
+    }
+    return <Link to={to} {...props} />;
+  }
+
+  if (to && typeof to === "object") {
+    const pathname = (to as { pathname?: string }).pathname;
+    if (pathname && pathname.startsWith("/") && !isExternal(pathname)) {
+      return (
+        <Link
+          to={{ ...to, pathname: getLocalizedUrl(pathname, locale) }}
+          {...props}
+        />
+      );
+    }
+    return <Link to={to} {...props} />;
+  }
+
+  return (
+    <Link
+      to={getLocalizedUrl(location.pathname + location.search, locale)}
+      {...props}
+    />
+  );
+}
+```
+
+### Étape 8 : Utiliser Intlayer dans vos pages
+
+Accédez à vos dictionnaires de contenu dans toute votre application :
+
+#### Page de redirection racine
+
+```tsx fileName="app/routes/page.tsx" codeFormat="typescript"
+// app/routes/page.tsx
+import { useLocale } from "react-intlayer";
+import { Navigate } from "react-router";
+
+export default function Page() {
+  const { locale } = useLocale();
+
+  return <Navigate replace to={locale} />;
+}
+```
+
+#### Page d'accueil localisée
+
+```tsx fileName="app/routes/[lang]/page.tsx" codeFormat="typescript"
+import { useIntlayer } from "react-intlayer";
+import LocalizedLink from "~/components/localized-link";
+
+export default function Page() {
+  const content = useIntlayer("page");
+
+  return (
+    <div style={{ padding: "2rem", textAlign: "center" }}>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+      <nav style={{ marginTop: "2rem" }}>
+        <LocalizedLink
+          to="/about"
+          style={{
+            display: "inline-block",
+            padding: "0.5rem 1rem",
+            backgroundColor: "#007bff",
+            color: "white",
+            textDecoration: "none",
+            borderRadius: "4px",
+          }}
+        >
+          {content.aboutLink}
+        </LocalizedLink>
+      </nav>
+    </div>
+  );
+}
+```
+
+> Pour en savoir plus sur le hook `useIntlayer`, consultez la [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/react-intlayer/useIntlayer.md).
+
+### Étape 9 : Créer un composant de changement de langue
+
+Créez un composant pour permettre aux utilisateurs de changer de langue :
+
+```tsx fileName="app/components/locale-switcher.tsx" codeFormat="typescript"
+import { getLocalizedUrl, getLocaleName } from "intlayer";
+import { useLocale } from "react-intlayer";
+import { useLocation, useNavigate } from "react-router";
+
+export default function LocaleSwitcher() {
+  const { locale, availableLocales, setLocale } = useLocale();
+  const location = useLocation();
+  const navigate = useNavigate();
+
+  const handleLocaleChange = (newLocale: string) => {
+    const localizedUrl = getLocalizedUrl(
+      location.pathname + location.search,
+      newLocale
+    );
+    setLocale(newLocale);
+    navigate(localizedUrl);
+  };
+
+  return (
+    <div style={{ margin: "1rem 0" }}>
+      <label htmlFor="locale-select">Choisir la langue : </label>
+      <select
+        id="locale-select"
+        value={locale}
+        onChange={(e) => handleLocaleChange(e.target.value)}
+        style={{ padding: "0.25rem", marginLeft: "0.5rem" }}
+      >
+        {availableLocales.map((availableLocale) => (
+          <option key={availableLocale} value={availableLocale}>
+            {getLocaleName(availableLocale)}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+}
+```
+
+> Pour en savoir plus sur le hook `useLocale`, consultez la [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/react-intlayer/useLocale.md).
+
+### Étape 10 : Ajouter la gestion des attributs HTML (optionnel)
+
+Créez un hook pour gérer les attributs lang et dir du HTML :
+
+```tsx fileName="app/hooks/useI18nHTMLAttributes.tsx" codeFormat="typescript"
+// app/hooks/useI18nHTMLAttributes.tsx
+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]);
+};
+```
+
+Ensuite, utilisez-le dans votre composant racine :
+
+```tsx fileName="app/root.tsx" codeFormat="typescript"
+// app/routes/layout.tsx
+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>
+  );
+}
+```
+
+### Étape 11 : Construisez et lancez votre application
+
+Construisez les dictionnaires de contenu et lancez votre application :
+
+```bash packageManager="npm"
+# Construire les dictionnaires Intlayer
+npm run intlayer:build
+
+# Démarrer le serveur de développement
+npm run dev
+```
+
+```bash packageManager="pnpm"
+# Construire les dictionnaires Intlayer
+pnpm intlayer:build
+
+# Démarrer le serveur de développement
+pnpm dev
+```
+
+```bash packageManager="yarn"
+# Construire les dictionnaires Intlayer
+yarn intlayer:build
+
+# Démarrer le serveur de développement
+yarn dev
+```
+
+### Étape 12 : Configurer TypeScript (Optionnel)
+
+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 :
+
+```json5 fileName="tsconfig.json"
+{
+  compilerOptions: {
+    // ... vos configurations TypeScript 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 dans votre fichier `.gitignore` :
+
+```plaintext fileName=".gitignore"
+# Ignorer les fichiers générés par Intlayer
+.intlayer
+```
+
+---
+
+## Déploiement en Production
+
+Lors du déploiement de votre application :
+
+1. **Construisez votre application :**
+
+   ```bash
+   npm run build
+   ```
+
+2. **Construisez les dictionnaires Intlayer :**
+
+   ```bash
+   npm run intlayer:build
+   ```
+
+3. **Déplacez `vite-intlayer` dans les dépendances** si vous utilisez un middleware en production :
+   ```bash
+   npm install vite-intlayer --save
+   ```
+
+Votre application prendra désormais en charge :
+
+- **Structure des URL** : `/en`, `/en/about`, `/tr`, `/tr/about`
+- **Détection automatique de la langue** basée sur les préférences du navigateur
+- **Routage sensible à la langue** avec React Router v7
+- **Support TypeScript** avec des types générés automatiquement
+- **Rendu côté serveur** avec une gestion correcte des langues
+
+## Extension VS Code
+
+Pour améliorer votre expérience de développement avec Intlayer, vous pouvez installer l’extension officielle **Intlayer VS Code Extension**.
+
+[Installer depuis le Marketplace VS Code](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+Cette extension offre :
+
+- **Autocomplétion** pour les clés de traduction.
+- **Détection d’erreurs en temps réel** pour les traductions manquantes.
+- **Aperçus en ligne** du contenu traduit.
+- **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 VS Code Intlayer](https://intlayer.org/doc/vs-code-extension).
+
+---
+
+## Aller plus loin
+
+Pour aller plus loin, vous pouvez implémenter l'[éditeur visuel](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/intlayer_visual_editor.md) ou externaliser votre contenu en utilisant le [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/intlayer_CMS.md).
+
+---
+
+## Références de la documentation
+
+- [Documentation Intlayer](https://intlayer.org)
+- [Documentation React Router v7](https://reactrouter.com/)
+- [Hook useIntlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/react-intlayer/useIntlayer.md)
+- [useLocale hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/react-intlayer/useLocale.md)
+- [Déclaration de contenu](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/dictionary/get_started.md)
+- [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/configuration.md)
+
+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
+
+| Version | Date      | Modifications              |
+| ------- | --------- | -------------------------- |
+| 5.8.2   | 2025-09-4 | Ajout pour React Router v7 |