- Documentation
- Environnement
- Intlayer avec Vite et React
Commencer à Internationaliser (i18n) avec Intlayer, Vite et React
Qu'est-ce qu'Intlayer ?
Intlayer est une bibliothèque d'internationalisation (i18n) open-source et innovante, conçue pour simplifier le support 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 le support TypeScript avec des types auto-générés, améliorant l'autocomplétion et la détection des erreurs.
- Bénéficier de fonctionnalités avancées, comme la détection dynamique de la langue et le changement.
Guide étape par étape pour configurer Intlayer dans une application Vite et React
Étape 1 : Installer les Dépendances
Installez les packages nécessaires en utilisant npm :
1npm install intlayer react-intlayer1yarn add intlayer react-intlayer1pnpm add intlayer react-intlayerÉtape 2 : Configuration de votre projet
Créer 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.
Étape 3 : Intégrer Intlayer dans votre Configuration Vite
Ajoutez le plugin intlayer dans votre configuration.
1import { defineConfig } from "vite";
2import react from "@vitejs/plugin-react-swc";
3import { intLayerPlugin } from "react-intlayer/vite";
4
5// https://vitejs.dev/config/
6export default defineConfig({
7 plugins: [react(), intLayerPlugin()],
8});Étape 4 : Déclarer Votre Contenu
Créez et gérez vos dictionnaires de contenu :
1// src/app.content.tsx
2import { t, type DeclarationContent } from "intlayer";
3import { type ReactNode } from "react";
4
5const appContent = {
6 key: "app",
7 content: {
8 viteLogo: t({
9 en: "Vite logo",
10 fr: "Logo Vite",
11 es: "Logo Vite",
12 }),
13 reactLogo: t({
14 en: "React logo",
15 fr: "Logo React",
16 es: "Logo React",
17 }),
18
19 title: "Vite + React",
20
21 count: t({
22 en: "count is ",
23 fr: "le compte est ",
24 es: "el recuento es ",
25 }),
26
27 edit: t<ReactNode>({
28 // N'oubliez pas d'importer React si vous utilisez un React node dans votre contenu
29 en: (
30 <>
31 Edit <code>src/App.tsx</code> and save to test HMR
32 </>
33 ),
34 fr: (
35 <>
36 Éditez <code>src/App.tsx</code> et enregistrez pour tester HMR
37 </>
38 ),
39 es: (
40 <>
41 Edita <code>src/App.tsx</code> y guarda para probar HMR
42 </>
43 ),
44 }),
45
46 readTheDocs: t({
47 en: "Click on the Vite and React logos to learn more",
48 fr: "Cliquez sur les logos Vite et React pour en savoir plus",
49 es: "Haga clic en los logotipos de Vite y React para obtener más información",
50 }),
51 },
52} satisfies DeclarationContent;
53
54export default appContent;Note : Si votre fichier de contenu inclut du code TSX, vous devriez envisager d'importer import React from "react"; dans votre fichier de contenu.
Voir comment déclarer vos fichiers de déclaration Intlayer.
Étape 5 : Utiliser Intlayer dans Votre Code
Accédez à vos dictionnaires de contenu dans toute votre application :
1import { useState } from "react";
2import reactLogo from "./assets/react.svg";
3import viteLogo from "/vite.svg";
4import "./App.css";
5import { LocaleSwitcher } from "./components/LangSwitcherDropDown";
6import { IntlayerProvider, useIntlayer } from "react-intlayer";
7
8function AppContent() {
9 const [count, setCount] = useState(0);
10 const content = useIntlayer("app");
11
12 return (
13 <>
14 <div>
15 <a href="https://vitejs.dev" target="_blank">
16 <img src={viteLogo} className="logo" alt={content.viteLogo.value} />
17 </a>
18 <a href="https://react.dev" target="_blank">
19 <img
20 src={reactLogo}
21 className="logo react"
22 alt={content.reactLogo.value}
23 />
24 </a>
25 </div>
26 <h1>{content.title}</h1>
27 <div className="card">
28 <button onClick={() => setCount((count) => count + 1)}>
29 {content.count}
30 {count}
31 </button>
32 <p>{content.edit}</p>
33 </div>
34 <p className="read-the-docs">{content.readTheDocs}</p>
35 <div className="absolute bottom-5 right-5 z-50">
36 <LocaleSwitcher />
37 </div>
38 </>
39 );
40}
41
42function App() {
43 return (
44 <IntlayerProvider>
45 <AppContent />
46 </IntlayerProvider>
47 );
48}
49
50export default App;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} />
(Optionnel) Étape 6 : Changer la langue de votre contenu
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 "react-intlayer";
3
4const LocaleSwitcher = () => {
5 const { setLocale } = useLocale();
6
7 return (
8 <button onClick={() => setLocale(Locales.English)}>
9 Change Language to English
10 </button>
11 );
12};(Optionnel) Étape 7 : Ajouter un Routage localisé à votre application
Le but de cette étape est de créer des routes uniques pour chaque langue. Cela est utile pour le SEO et les URL optimisées pour le SEO. Exemple :
1// /dashboard
2// /es/dashboard
3// /fr/dashboardPar défaut, les routes ne sont pas préfixées pour la locale par défaut. Si vous souhaitez préfixer la locale par défaut, vous pouvez définir l'option middleware.prefixDefault sur true dans votre configuration. Consultez la documentation de configuration pour plus d'informations.
Pour ajouter un routage localisé à votre application, vous pouvez créer un composant LocaleRouter qui englobe les routes de votre application et gère le routage basé sur la locale. Voici un exemple utilisant React Router :
1// Importation des dépendances et fonctions nécessaires
2import { Locales, getConfiguration, getPathWithoutLocale } from "intlayer"; // Fonctions utilitaires et types de 'intlayer'
3import { FC, PropsWithChildren } from "react"; // Types React pour les composants fonctionnels et les props
4import { IntlayerProvider } from "react-intlayer"; // Fournisseur pour le contexte d'internationalisation
5import {
6 BrowserRouter,
7 Routes,
8 Route,
9 useParams,
10 Navigate,
11 useLocation,
12} from "react-router-dom"; // Composants Router pour gérer la navigation
13
14// Destructuration de la configuration d'Intlayer
15const { internationalization, middleware } = getConfiguration();
16const { locales, defaultLocale } = internationalization;
17
18/**
19 * Un composant qui gère la localisation et enveloppe les enfants avec le contexte de locale approprié.
20 * Il gère la détection et la validation de la locale basée sur l'URL.
21 */
22const AppLocalized: FC<PropsWithChildren> = ({ children }) => {
23 const path = useLocation().pathname; // Obtenir le chemin de l'URL actuelle
24 const { locale } = useParams<{ locale: Locales }>(); // Extraire le paramètre de locale de l'URL
25
26 // Déterminer la locale actuelle, en revenant à la locale par défaut si non fournie
27 const currentLocale = locale ?? defaultLocale;
28
29 // Supprimer le préfixe de locale du chemin pour construire un chemin de base
30 const pathWithoutLocale = getPathWithoutLocale(
31 path // Chemin de l'URL actuelle
32 );
33
34 /**
35 * Si middleware.prefixDefault est vrai, la locale par défaut doit toujours être préfixée.
36 */
37 if (middleware.prefixDefault) {
38 // Valider la locale
39 if (!locale || !locales.includes(locale)) {
40 // Rediriger vers la locale par défaut avec le chemin mis à jour
41 return (
42 <Navigate
43 to={`/${defaultLocale}/${pathWithoutLocale}`}
44 replace // Remplacer l'entrée actuelle de l'historique par la nouvelle
45 />
46 );
47 }
48
49 // Envelopper les enfants avec le IntlayerProvider et définir la locale actuelle
50 return (
51 <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
52 );
53 } else {
54 /**
55 * Lorsque middleware.prefixDefault est faux, la locale par défaut n'est pas préfixée.
56 * Assurez-vous que la locale actuelle est valide et n'est pas la locale par défaut.
57 */
58 if (
59 currentLocale.toString() !== defaultLocale.toString() &&
60 !locales
61 .filter(
62 (locale) => locale.toString() !== defaultLocale.toString() // Exclure la locale par défaut
63 )
64 .includes(currentLocale) // Vérifier si la locale actuelle est dans la liste des locales valides
65 ) {
66 // Rediriger vers le chemin sans préfixe de locale
67 return <Navigate to={pathWithoutLocale} replace />;
68 }
69
70 // Envelopper les enfants avec le IntlayerProvider et définir la locale actuelle
71 return (
72 <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
73 );
74 }
75};
76
77/**
78 * Un composant de routage qui met en place des routes spécifiques à la locale.
79 * Il utilise React Router pour gérer la navigation et rendre des composants localisés.
80 */
81export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
82 <BrowserRouter>
83 <Routes>
84 <Route
85 // Modèle de route pour capturer la locale (par exemple, /en/, /fr/) et correspondre à tous les chemins ultérieurs
86 path="/:locale/*"
87 element={<AppLocalized>{children}</AppLocalized>} // Enveloppe les enfants avec la gestion de la locale
88 />
89
90 {
91 // Si le préfixage de la locale par défaut est désactivé, rendre les enfants directement à la racine
92 !middleware.prefixDefault && (
93 <Route
94 path="*"
95 element={<AppLocalized>{children}</AppLocalized>} // Enveloppe les enfants avec la gestion de la locale
96 />
97 )
98 }
99 </Routes>
100 </BrowserRouter>
101);En parallèle, vous pouvez également utiliser le intLayerMiddlewarePlugin pour ajouter un routage côté serveur à votre application. Ce plugin détectera automatiquement la locale actuelle basée sur 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 de langue du navigateur de l'utilisateur. Si aucune locale n'est détectée, il redirigera vers la locale par défaut.
1import { defineConfig } from "vite";
2import react from "@vitejs/plugin-react-swc";
3import { intLayerPlugin, intLayerMiddlewarePlugin } from "react-intlayer/vite";
4
5// https://vitejs.dev/config/
6export default defineConfig({
7 plugins: [react(), intLayerPlugin(), intLayerMiddlewarePlugin()],
8});(Optionnel) Étape 8 : Changer l'URL lorsque la locale change
Pour changer l'URL lorsque la locale change, vous pouvez utiliser la prop onLocaleChange fournie par le hook useLocale. En parallèle, vous pouvez aussi utiliser les hooks useLocation et useNavigate de react-router-dom pour mettre à jour le chemin de l'URL.
1import { Locales, getLocalizedUrl } from "intlayer";
2import { useLocale } from "react-intlayer";
3import { useLocation, useNavigate } from "react-router-dom";
4
5const LocaleSwitcher = () => {
6 const location = useLocation(); // Obtenir le chemin de l'URL actuelle. Exemple : /fr/about
7 const navigate = useNavigate();
8
9 const changeUrl = (locale: Locales) => {
10 // Construire l'URL avec la locale mise à jour
11 // Exemple : /es/about avec la locale définie sur Espagnol
12 const pathWithLocale = getLocalizedUrl(location.pathname, locale);
13
14 // Mettre à jour le chemin de l'URL
15 navigate(pathWithLocale);
16 };
17
18 const { setLocale } = useLocale({
19 onLocaleChange: changeUrl,
20 });
21
22 return (
23 <button onClick={() => setLocale(Locales.English)}>
24 Change Language to English
25 </button>
26 );
27};Configurer TypeScript
Intlayer utilise l'augmentation de module pour bénéficier de TypeScript et rendre votre codebase plus solide.
Assurez-vous que votre configuration TypeScript inclut les types auto-générés.
1// tsconfig.json
2
3{
4 // votre configuration personnalisée
5 include: [
6 "src",
7 "types", // <- Inclure les types auto-générés
8 ],
9}Configuration Git
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