- Documentation
- Environnement
- Intlayer avec React CRA
Prendre en main l'internationalisation (i18n) avec Intlayer et React Create App
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.
Avec Intlayer, vous pouvez :
- Gérer facilement les traductions à l'aide de dictionnaires déclaratifs au niveau du composant.
- Localiser dynamiquement les métadonnées, les routes et le contenu.
- Assurer la prise en charge de TypeScript avec des types autogé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 et le changement de localisation dynamiques.
Guide étape par étape pour configurer Intlayer dans une application 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éez 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 langues
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 CRA
Changez vos scripts pour utiliser react-intlayer
1 "scripts": {
2 "build": "react-intlayer build",
3 "start": "react-intlayer start",
4 "transpile": "intlayer build"
5 },Remarque : les scripts react-intlayer sont basés sur craco. Vous pouvez également mettre en œuvre votre propre configuration basée sur le plugin craco d'intlayer. Voir un exemple ici.
É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 getStarted: t<ReactNode>({
9 en: (
10 <>
11 Edit <code>src/App.tsx</code> and save to reload
12 </>
13 ),
14 fr: (
15 <>
16 Éditez <code>src/App.tsx</code> et enregistrez pour recharger
17 </>
18 ),
19 es: (
20 <>
21 Edita <code>src/App.tsx</code> y guarda para recargar
22 </>
23 ),
24 }),
25 reactLink: {
26 href: "https://reactjs.org",
27 content: t({
28 en: "Learn React",
29 fr: "Apprendre React",
30 es: "Aprender React",
31 }),
32 },
33 },
34} satisfies DeclarationContent;
35
36export default appContent;Voir comment déclarer vos fichiers de déclaration Intlayer.
Étape 5 : Utiliser Intlayer dans votre code
Accédez à vos dictionnaires de contenu tout au long de votre application :
1import logo from "./logo.svg";
2import "./App.css";
3import { IntlayerProvider, useIntlayer } from "react-intlayer";
4import { LocaleSwitcher } from "./components/LangSwitcherDropDown";
5
6function AppContent() {
7 const content = useIntlayer("app");
8
9 return (
10 <header className="App-header">
11 <img src={logo} className="App-logo" alt="logo" />
12
13 {content.getStarted}
14 <a
15 className="App-link"
16 href={content.reactLink.href.value}
17 target="_blank"
18 rel="noopener noreferrer"
19 >
20 {content.reactLink.content}
21 </a>
22 </header>
23 );
24}
25
26function App() {
27 return (
28 <IntlayerProvider>
29 <div className="App">
30 {/* Pour utiliser le hook useIntlayer correctement, vous devez accéder à vos données dans un composant enfant */}
31 <AppContent />
32 </div>
33 <div className="absolute bottom-5 right-5 z-50">
34 <LocaleSwitcher />
35 </div>
36 </IntlayerProvider>
37 );
38}
39
40export default App;Remarque : 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.French)}>
9 Changer la langue en Français
10 </button>
11 );
12};(Optionnel) Étape 7 : Ajouter un routage localisé à votre application
L'objectif de cette étape est de créer des routes uniques pour chaque langue. Ceci est utile pour le SEO et les URL optimisées pour le référencement. 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. Voir la documentation de configuration pour plus d'informations.
Pour ajouter un routage localisé à votre application, vous pouvez créer un composant LocaleRouter qui enveloppe les routes de votre application et gère le routage en fonction de la locale. Voici un exemple utilisant React Router :
1// Importation des dépendances et fonctions nécessaires
2import { Locales, getConfiguration, getPathWithoutLocale } from "intlayer"; // Fonctions et types utilitaires 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 de routage 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 d'URL actuel
24 const { locale } = useParams<{ locale: Locales }>(); // Extraire le paramètre de locale de l'URL
25
26 // Déterminer la locale actuelle, en retombant sur 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 = removeLocaleFromUrl(
31 path // Chemin d'URL actuel
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 les composants localisés.
80 */
81export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
82 <BrowserRouter>
83 <Routes>
84 <Route
85 // Motif de route pour capturer la locale (par exemple, /en/, /fr/) et correspondre à tous les chemins suivants
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 directement les enfants à 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);(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 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 actuel. 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 réglée 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.French)}>
24 Changer la langue en Français
25 </button>
26 );
27};Configurez TypeScript
Intlayer utilise l'augmentation de module pour bénéficier de TypeScript et renforcer votre codebase.
Assurez-vous que votre configuration TypeScript comprend les types autogé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 commettre dans votre dépôt Git.
Pour faire cela, 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