Traduire votre application Expo et React Native | Internationalisation (i18n)

Table des matières

Pourquoi Intlayer plutôt que des alternatives ?

Par rapport aux solutions principales telles que react-native-localize ou i18next, Intlayer est une solution qui comprend des optimisations intégrées telles que :

1. 1

   Installer les dépendances

   Voir Modèle d'application sur GitHub.

   Depuis votre projet React Native, installez les packages suivants :

   bash

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   npx intlayer@canary init --interactive    # v9# npx intlayer init                       # v8

   Le flag --interactive est facultatif. 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-native-intlayer

   Packages

   • intlayer
     La boîte à outils i18n principale pour la configuration, le contenu des dictionnaires, la génération de types et les commandes CLI.

   • react-native-intlayer
     Intégration React Native qui fournit les fournisseurs de contexte et les hooks React que vous utiliserez pour obtenir et changer les locales, les polyfills React Native et le plugin Metro pour intégrer Intlayer avec le bundler React Native. Il ré-exporte tout depuis react-intlayer, vous n'avez donc besoin que de ce seul package dans une application React Native.

   ---

2. 2

   Créer une configuration Intlayer

   Dans la racine de votre projet (ou à tout autre endroit pratique), créez un fichier de configuration Intlayer. Il pourrait ressembler à ceci :

   intlayer.config.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   /**
    * Si les types Locales ne sont pas disponibles, essayez de définir moduleResolution à "bundler" dans votre tsconfig.json
    */
   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // ... Ajoutez toutes les autres locales dont vous avez besoin
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;

   Dans cette configuration, vous pouvez :

   • Configurer votre liste de locales prises en charge.
   • Définir une locale par défaut.
   • Plus tard, vous pourrez ajouter des options plus avancées (par exemple, des logs, des répertoires de contenu personnalisés, etc.).
   • Consultez la documentation de configuration d'Intlayer pour plus d'informations.
3. 3

   Ajouter le plugin Metro

   Metro est un bundler pour React Native. C'est le bundler par défaut pour les projets React Native créés avec la commande react-native init. Pour utiliser Intlayer avec Metro, vous devez ajouter le plugin dans votre fichier metro.config.js :

   metro.config.js

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   const { getDefaultConfig } = require("expo/metro-config");const { configMetroIntlayer } = require("react-native-intlayer/metro");module.exports = (async () => {  const defaultConfig = getDefaultConfig(__dirname);  return await configMetroIntlayer(defaultConfig);})();

   Note : configMetroIntlayer est une fonction asynchrone. Utilisez configMetroIntlayerSync à la place si vous souhaitez l'utiliser de manière synchrone, ou éviter une IIFE (Immediately Invoked Function Expression). Note : configMetroIntlayerSync ne permet pas de construire les dictionnaires intlayer au démarrage du serveur

4. 4

   Ajouter le fournisseur Intlayer

   Pour garder synchronisée la langue de l'utilisateur dans toute votre application, vous devez envelopper votre composant racine avec le composant IntlayerProvider de react-native-intlayer.

   Importez toujours depuis react-native-intlayer. Son IntlayerProvider inclut des polyfills pour l'API web utilisée par Intlayer, et le package ré-exporte tous les hooks et utilitaires de react-intlayer.

   De plus, vous devez ajouter la fonction intlayerPolyfill à votre fichier index.js pour vous assurer qu'Intlayer puisse fonctionner correctement.

   app/_layout.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { Stack } from "expo-router";
   import { getLocales } from "expo-localization";
   import { IntlayerProvider } from "react-native-intlayer";
   import { type FC } from "react";
   
   const getDeviceLocale = () => getLocales()[0]?.languageTag;
   
   const RootLayout: FC = () => {
     return (
       <IntlayerProvider defaultLocale={getDeviceLocale()}>
         <Stack>
           <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
         </Stack>
       </IntlayerProvider>
     );
   };
   
   export default RootLayout;

5. 5

   Déclarez Votre Contenu

   Créez des fichiers de déclaration de contenu n'importe où dans votre projet (généralement dans src/), en utilisant l'un des formats d'extension pris en charge par Intlayer :

   • .content.json
   • .content.jsonc
   • .content.json5
   • .content.ts
   • .content.tsx
   • .content.js
   • .content.jsx
   • .content.mjs
   • .content.mjx
   • .content.cjs
   • .content.md
   • .content.mdx
   • .content.yaml
   • .content.yml
   • etc.

   Expo Router (web) : gardez les fichiers .content.* en dehors du répertoire app/. Expo Router traite chaque fichier JavaScript/TypeScript dans app/ comme une route. Sur le web, sa découverte de routes scanne directement le système de fichiers et ne respecte pas le resolver.blockList de Metro, donc un *.content.ts co-localisé est enregistré comme une route. Un fichier tel que app/(tabs)/_layout.content.ts est même analysé comme un layout (la partie .content est lue comme un suffixe de plateforme), ce qui entre en conflit avec le vrai _layout.tsx et renvoie une erreur :

   plaintext

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   The layouts "./(tabs)/_layout.content.ts" and "./(tabs)/_layout.tsx" conflict on the route "/(tabs)/_layout.content". Remove or rename one of these files.

   Placez vos déclarations dans un répertoire en dehors de app/ (par exemple content/ ou src/content/). Intlayer découvre les fichiers .content.* n'importe où dans le projet et les dictionnaires sont référencés par leur key, donc aucune modification d'importation n'est nécessaire. En natif, ce n'est pas requis (le blockList de Metro les cache déjà), mais l'utilisation d'un répertoire autre que app/ permet aux deux plateformes de fonctionner.

   Exemple (TypeScript avec des nœuds TSX pour React Native) :

   src/app.content.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { t, type Dictionary } from "intlayer";
   import type { ReactNode } from "react";
   
   /**
    * Dictionnaire de contenu pour notre domaine "app"
    */
   import { t, type Dictionary } from "intlayer";
   
   const homeScreenContent = {
     key: "home-screen",
     content: {
       title: t({
         en: "Welcome!",
         fr: "Bienvenue!",
         es: "¡Bienvenido!",
       }),
     },
   } satisfies Dictionary;
   
   export default homeScreenContent;

   Pour plus de détails sur les déclarations de contenu, consultez la documentation du contenu d'Intlayer.

   ---

6. 6

   Utiliser Intlayer dans vos composants

   Utilisez le hook useIntlayer dans les composants enfants pour obtenir du contenu localisé.

   Exemple

   app/(tabs)/index.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { Image, StyleSheet, Platform } from "react-native";
   import { useIntlayer } from "react-native-intlayer";
   import { HelloWave } from "@/components/HelloWave";
   import ParallaxScrollView from "@/components/ParallaxScrollView";
   import { ThemedText } from "@/components/ThemedText";
   import { ThemedView } from "@/components/ThemedView";
   import { type FC } from "react";
   
   const HomeScreen = (): FC => {
     const { title, steps } = useIntlayer("home-screen");
   
     return (
       <ParallaxScrollView
         headerBackgroundColor={{ light: "#A1CEDC", dark: "#1D3D47" }}
         headerImage={
           <Image
             source={require("@/assets/images/partial-react-logo.png")}
             style={styles.reactLogo}
           />
         }
       >
         <ThemedView style={styles.titleContainer}>
           <ThemedText type="title">{title}</ThemedText>
           <HelloWave />
         </ThemedView>
       </ParallaxScrollView>
     );
   };
   
   const styles = StyleSheet.create({
     titleContainer: {
       flexDirection: "row",
       alignItems: "center",
       gap: 8,
     },
   });
   
   export default HomeScreen;

   Lors de l'utilisation de content.someKey dans des props basées sur des chaînes (par exemple, le title d'un bouton ou les children d'un composant Text), appelez content.someKey.value pour obtenir la chaîne réelle.

   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.

   ---

7. 7

   Changer la langue de l'application

   Facultatif

   Pour changer la langue depuis vos composants, vous pouvez utiliser la méthode setLocale du hook useLocale :

   src/components/LocaleSwitcher.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { type FC } from "react";
   import { View, Text, TouchableOpacity, StyleSheet } from "react-native";
   import { getLocaleName } from "intlayer";
   import { useLocale } from "react-native-intlayer";
   
   export const LocaleSwitcher: FC = () => {
     const { setLocale, availableLocales } = useLocale();
   
     return (
       <View style={styles.container}>
         {availableLocales.map((locale) => (
           <TouchableOpacity
             key={locale}
             style={styles.button}
             onPress={() => setLocale(locale)}
           >
             <Text style={styles.text}>{getLocaleName(locale)}</Text>
           </TouchableOpacity>
         ))}
       </View>
     );
   };
   
   const styles = StyleSheet.create({
     container: {
       flexDirection: "row",
       justifyContent: "center",
       alignItems: "center",
       gap: 8,
     },
     button: {
       paddingVertical: 6,
       paddingHorizontal: 12,
       borderRadius: 6,
       backgroundColor: "#ddd",
     },
     text: {
       fontSize: 14,
       fontWeight: "500",
       color: "#333",
     },
   });

   Cela déclenche un nouveau rendu de tous les composants qui utilisent le contenu Intlayer, affichant désormais les traductions pour la nouvelle locale.

   Voir la documentation de useLocale pour plus de détails.

Configurer TypeScript (si vous utilisez TypeScript)

Intlayer génère des définitions de types dans un dossier caché (par défaut .intlayer) pour améliorer l'autocomplétion et détecter les erreurs de traduction :

// tsconfig.json{  // ... votre configuration TS existante  "include": [    "src", // votre code source    ".intlayer/types/**/*.ts", // <-- assurez-vous que les types générés automatiquement sont inclus    // ... tout autre élément que vous incluez déjà  ],}

C'est ce qui permet des fonctionnalités telles que :

• Autocomplétion pour vos clés de dictionnaire.
• Vérification de type qui avertit si vous accédez à une clé inexistante ou si le type ne correspond pas.

Configuration Git

Pour éviter de committer les fichiers générés automatiquement par Intlayer, ajoutez ce qui suit à votre .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 :

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

Aller plus loin

• Éditeur Visuel : Utilisez le Éditeur Visuel Intlayer pour gérer les traductions visuellement.
• Intégration CMS : Vous pouvez également externaliser et récupérer le contenu de votre dictionnaire depuis un CMS.
• Commandes CLI : Explorez le CLI Intlayer pour des tâches telles que l'extraction des traductions ou la vérification des clés manquantes.

Profitez de la création de vos applications React Native avec une i18n pleinement optimisée grâce à Intlayer !

Débogage

React Native peut être moins stable que React Web, donc faites particulièrement attention à l'alignement des versions.

Intlayer cible principalement l'API Web Intl ; sur React Native, vous devez inclure les polyfills appropriés.

Checklist :

• Utilisez les dernières versions de intlayer et react-native-intlayer.
• Activez le polyfill Intlayer.
• Si vous utilisez getLocaleName ou d'autres utilitaires basés sur l'API Intl, importez ces polyfills tôt (par exemple dans index.js ou App.tsx) :

import "intl";import "@formatjs/intl-getcanonicallocales/polyfill";import "@formatjs/intl-locale/polyfill";import "@formatjs/intl-pluralrules/polyfill";import "@formatjs/intl-displaynames/polyfill";import "@formatjs/intl-listformat/polyfill";import "@formatjs/intl-numberformat/polyfill";import "@formatjs/intl-relativetimeformat/polyfill";import "@formatjs/intl-datetimeformat/polyfill";

• Vérifiez votre configuration Metro (resolver aliases, asset plugins, chemins tsconfig) si les modules ne se résolvent pas.