Commencer l'internationalisation (i18n) avec Intlayer et React Native

Voir le Modèle d'Application sur GitHub.

Qu'est-ce que Intlayer ?

Intlayer est une bibliothèque d'internationalisation (i18n) innovante et open-source qui simplifie la prise en charge multilingue dans les applications modernes. Elle fonctionne dans de nombreux environnements JavaScript/TypeScript, y compris React Native (via le package react-intlayer).

Avec Intlayer, vous pouvez :

• Gérer facilement les traductions en utilisant des dictionnaires déclaratifs au niveau des composants.
• Assurer la prise en charge de TypeScript avec des types générés automatiquement.
• Localiser dynamiquement le contenu, y compris les chaînes d'interface utilisateur (et dans React pour le web, elle peut aussi localiser les métadonnées HTML, etc.).
• Bénéficier de fonctionnalités avancées, comme la détection et le changement dynamique de la langue.

Étape 1 : Installer les dépendances

Depuis votre projet React Native, installez les packages suivants :

bash packageManager="npm"npm install intlayer react-intlayernpm install --save-dev 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-intlayer
  Intégration React qui fournit les fournisseurs de contexte et les hooks React que vous utiliserez dans React Native pour obtenir et changer les locales.

• react-native-intlayer
  Intégration React Native qui fournit le plugin Metro pour intégrer Intlayer avec le bundler React Native.

Étape 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 :

/** * 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.

Étape 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 :

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

Étape 4 : Ajouter le fournisseur Intlayer

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

De plus, vous devez ajouter la fonction intlayerPolyfill dans votre fichier index.js pour garantir que Intlayer fonctionne correctement.

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

Étape 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.ts
• .content.tsx
• .content.js
• .content.jsx
• .content.mjs
• .content.mjx
• .content.cjs
• .content.cjx
• etc.

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

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.

Étape 4 : Utiliser Intlayer dans vos composants

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

Exemple

import { Image, StyleSheet, Platform } from "react-native";import { useIntlayer } from "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.

(Optionnel) Étape 5 : Changer la langue de l'application

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

import { type FC } from "react";import { View, Text, TouchableOpacity, StyleSheet } from "react-native";import { getLocaleName } from "intlayer";import { useLocale } from "react-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 !

Historique de la documentation

• 5.5.10 - 2025-06-29 : Historique initial