Commencer avec l'internationalisation (i18n) avec Intlayer, Lynx et React

Voir Application Template sur GitHub.

Qu'est-ce qu'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 Lynx (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, il peut également localiser les métadonnées HTML, etc.).
• Bénéficier de fonctionnalités avancées, comme la détection et le changement dynamiques de la langue.

Étape 1 : Installer les dépendances

Depuis votre projet Lynx, installez les packages suivants :

npm install intlayer react-intlayer lynx-intlayer

Packages

• intlayer
  L'outil i18n principal 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 Lynx pour obtenir et changer les langues.

• lynx-intlayer
  Intégration Lynx qui fournit le plugin pour intégrer Intlayer avec le bundler Lynx.

Étape 2 : Créer une configuration Intlayer

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

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // ... Ajoutez toutes les autres langues dont vous avez besoin    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

Dans cette configuration, vous pouvez :

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

Étape 3 : Ajouter le plugin Intlayer au bundler Lynx

Pour utiliser Intlayer avec Lynx, vous devez ajouter le plugin à votre fichier lynx.config.ts :

import { defineConfig } from "@lynx-js/rspeedy";import { pluginIntlayerLynx } from "lynx-intlayer/plugin";export default defineConfig({  plugins: [    // ... autres plugins    pluginIntlayerLynx(),  ],});

Étape 4 : Ajouter le fournisseur Intlayer

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

De plus, vous devez ajouter le fichier de fonction intlayerPolyfill pour garantir qu'Intlayer fonctionne correctement.

import { root } from "@lynx-js/react";import { App } from "./App.js";import { IntlayerProvider } from "react-intlayer";import { intlayerPolyfill } from "lynx-intlayer";intlayerPolyfill();root.render(  <IntlayerProvider>    <App />  </IntlayerProvider>);if (import.meta.webpackHot) {  import.meta.webpackHot.accept();}

Étape 5 : Déclarer 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 Lynx) :

import { t, type Dictionary } from "intlayer";const appContent = {  key: "app",  content: {    title: "React",    subtitle: t({      fr: "sur Lynx",      en: "on Lynx",      es: "en Lynx",    }),    description: t({      fr: "Appuyez sur le logo et amusez-vous!",      en: "Tap the logo and have fun!",      es: "¡Toca el logo y diviértete!",    }),    hint: [      t({        fr: "Modifier",        en: "Edit",        es: "Editar",      }),      " src/App.tsx ",      t({        fr: "pour voir les mises à jour!",        en: "to see updates!",        es: "para ver actualizaciones!",      }),    ],  },} satisfies Dictionary;export default appContent;

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

Étape 4 : Utiliser Intlayer dans vos composants

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

import { useCallback, useState } from "@lynx-js/react";import { useIntlayer } from "react-intlayer";import "./App.css";import arrow from "./assets/arrow.png";import lynxLogo from "./assets/lynx-logo.png";import reactLynxLogo from "./assets/react-logo.png";import { LocaleSwitcher } from "./components/LocaleSwitcher.jsx";export const App = () => {  const [alterLogo, setAlterLogo] = useState(false);  const { title, subtitle, description, hint } = useIntlayer("app");  const onTap = useCallback(() => {    // changer uniquement l'arrière-plan    setAlterLogo(!alterLogo);  }, [alterLogo]);  return (    <view>      <view className="Background" />      <view className="App">        <view className="Banner">          <view className="Logo" bindtap={onTap}>            {alterLogo ? (              <image src={reactLynxLogo} className="Logo--react" />            ) : (              <image src={lynxLogo} className="Logo--lynx" />            )}          </view>          <text className="Title">{title}</text>          <text className="Subtitle">{subtitle}</text>        </view>        <view className="Content">          <image src={arrow} className="Arrow" />          <text className="Description">{description}</text>          <text className="Hint">            {hint[0]}            <text style={{ fontStyle: "italic" }}>{hint[1]}</text>            {hint[2]}          </text>        </view>        <LocaleSwitcher />        <view style={{ flex: 1 }}></view>      </view>    </view>  );};

Lorsque vous utilisez content.someKey dans des propriétés 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 les langues directement depuis vos composants, vous pouvez utiliser la méthode setLocale du hook useLocale :

import { type FC } from "react";import { getLocaleName } from "intlayer";import { useLocale } from "react-intlayer";export const LocaleSwitcher: FC = () => {  const { setLocale, availableLocales, locale } = useLocale();  return (    <view      style={{        display: "flex",        flexDirection: "row",        justifyContent: "center",        alignItems: "center",        gap: 10,      }}    >      {availableLocales.map((localeEl) => (        <text          key={localeEl}          style={{            color: localeEl === locale ? "#fff" : "#888",            fontSize: "12px",          }}          bindtap={() => setLocale(localeEl)}        >          {getLocaleName(localeEl)}        </text>      ))}    </view>  );};

Cela déclenche un nouveau rendu de tous les composants utilisant le contenu d'Intlayer, affichant désormais les traductions pour la nouvelle langue.

Consultez 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à  ],}

Cela permet des fonctionnalités comme :

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

Configuration Git

Pour éviter de commettre 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

Aller plus loin

• Éditeur visuel : Utilisez l'é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 comme extraire des traductions ou vérifier les clés manquantes.