Localisation avec Lingui.js : Fichiers PO, i18n React et automatisation

Lingui.js est un framework d'internationalisation (i18n) léger mais puissant pour les applications JavaScript et React. Il utilise des fichiers PO (Portable Object) conformes aux standards de l'industrie pour les catalogues de traduction, des macros puissantes à la compilation pour une expérience développeur fluide, et produit des bundles optimisés de moins de 2 ko. Ce guide couvre tout, de la configuration du projet aux flux de travail des fichiers PO, la pluralisation et l'automatisation des traductions avec l10n.dev.

Pourquoi Lingui.js pour l'i18n ?

Lingui.js se distingue parmi les bibliothèques i18n JavaScript par sa combinaison d'expérience développeur, de performance et de flux de travail de traduction professionnels :

• Propre et lisible : Écrivez vos traductions naturellement en utilisant des macros JSX - la bibliothèque les compile en ICU MessageFormat en arrière-plan.
• Universel : @lingui/core fonctionne dans n'importe quel projet JavaScript, tandis que @lingui/react ajoute des composants spécifiques à React, incluant le support des React Server Components (RSC).
• Support complet du texte enrichi : Utilisez des composants React à l'intérieur des messages traduisibles de manière transparente - les liens, le texte en gras, les icônes et tout JSX sont entièrement pris en charge.
• Format de fichier PO : Utilise le format PO standard de l'industrie, pris en charge par pratiquement tous les outils de traduction, TMS et flux de travail de traducteurs professionnels.
• Léger et optimisé : La bibliothèque principale pèse moins de 2 ko compressée (gzipped), les composants React n'ajoutent que 1,3 ko. Les données non essentielles sont supprimées à la compilation.
• Prêt pour les traductions par IA : Les descriptions de messages et les commentaires de contexte de Lingui fournissent aux traducteurs IA les informations nécessaires pour produire des traductions précises et adaptées au contexte.

Installation

Installez les packages principaux et les outils de développement de Lingui. Les packages d'exécution (@lingui/core et @lingui/react) sont nécessaires en production, tandis que la CLI, le plugin Vite et la macro Babel sont réservés au développement :

npm install @lingui/core @lingui/react
npm install --save-dev @lingui/cli @lingui/vite-plugin @lingui/babel-plugin-lingui-macro

Configuration

Lingui nécessite deux fichiers de configuration : la configuration Lingui (définissant les locales et les chemins des catalogues) et la configuration de votre outil de build (pour activer les macros à la compilation).

Configuration de Lingui

Créez un fichier lingui.config.js à la racine de votre projet. Il définit votre locale source, les locales cibles, l'emplacement de stockage des catalogues PO et le format du catalogue. Le format PO est le choix par défaut et recommandé :

// lingui.config.js
import { defineConfig } from "@lingui/cli";
import { formatter } from "@lingui/format-po";

export default defineConfig({
  sourceLocale: "en",
  locales: ["en", "fr", "de", "ja", "es", "zh-CN"],
  catalogs: [
    {
      path: "<rootDir>/src/locales/{locale}/messages",
      include: ["src"],
    },
  ],
  format: formatter({ lineNumbers: false }),
});

Configuration de Vite

Si vous utilisez Vite, ajoutez le plugin Lingui avec le plugin React et la macro Babel. Cela permet la transformation des messages à la compilation et la compilation des catalogues à la volée :

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingui } from "@lingui/vite-plugin";

export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: ["@lingui/babel-plugin-lingui-macro"],
      },
    }),
    lingui(),
  ],
});

Le format de fichier PO

PO (Portable Object) est le format de fichier de traduction standard de l'industrie, issu du système GNU gettext. Lingui utilise PO comme format de catalogue par défaut car il est largement pris en charge par les outils de traduction, les plateformes TMS et les traducteurs professionnels du monde entier.

• Lisible : Même les gros fichiers de traduction restent lisibles par l'humain avec des paires msgid/msgstr claires.
• Commentaires du traducteur : Prend en charge les commentaires #. qui transmettent directement des descriptions de contexte aux traducteurs.
• Références sources : Chaque message inclut des commentaires #: fichier:ligne montrant exactement où il est utilisé dans votre base de code.
• Support du contexte : Utilisez msgctxt pour lever l'ambiguïté sur des chaînes identiques ayant des significations différentes selon le contexte.
• Support d'outils universel : Compatible avec pratiquement tous les systèmes de gestion de traduction (TMS), outils TAO et plateformes de localisation.

Fichier PO extrait (messages sources)

#: src/components/WelcomeBanner.js:6
msgid "Welcome to our platform"
msgstr ""

#: src/components/WelcomeBanner.js:8
msgid "Hello {userName}, check out your <0>dashboard</0> to get started."
msgstr ""

#: src/components/CartSummary.js:5
msgid "{itemCount, plural, =0 {Your cart is empty} one {You have # item in your cart} other {You have # items in your cart}}"
msgstr ""

Fichier PO traduit (français)

Après la traduction, chaque msgstr est rempli avec la version localisée. Lingui préserve la syntaxe ICU MessageFormat, les balises indexées pour les composants React et les variables de remplacement dans toutes les traductions.

#: src/components/WelcomeBanner.js:6
msgid "Welcome to our platform"
msgstr "Bienvenue sur notre plateforme"

#: src/components/WelcomeBanner.js:8
msgid "Hello {userName}, check out your <0>dashboard</0> to get started."
msgstr "Bonjour {userName}, consultez votre <0>tableau de bord</0> pour commencer."

#: src/components/CartSummary.js:5
msgid "{itemCount, plural, =0 {Your cart is empty} one {You have # item in your cart} other {You have # items in your cart}}"
msgstr "{itemCount, plural, =0 {Votre panier est vide} one {Vous avez # article dans votre panier} other {Vous avez # articles dans votre panier}}"

Structure du projet

Organisez vos catalogues PO dans un répertoire locales avec un sous-dossier par locale. La CLI Lingui crée et met à jour automatiquement ces fichiers lors de l'extraction. Les modules JS compilés sont générés au moment de la construction et ne doivent pas être modifiés manuellement.

src/
├── locales/
│   ├── en/
│   │   └── messages.po       ← Source (English)
│   ├── fr/
│   │   └── messages.po       ← French
│   ├── de/
│   │   └── messages.po       ← German
│   ├── ja/
│   │   └── messages.po       ← Japanese
│   ├── es/
│   │   └── messages.po       ← Spanish
│   └── zh-CN/
│       └── messages.po       ← Chinese Simplified
├── components/
├── i18n.ts
├── App.tsx
└── ...

Traduction des composants React

Lingui propose deux approches principales pour marquer les messages : les macros JSX pour le contenu des composants et le hook useLingui pour les chaînes impératives. Ce sont deux macros de compilation qui produisent une sortie optimisée.

La macro Trans

Enveloppez tout contenu JSX dans la macro Trans pour le rendre traduisible. Les variables, les éléments HTML et les composants React sont entièrement pris en charge - la macro les transforme automatiquement en ICU MessageFormat avec des balises indexées.

import { Trans } from "@lingui/react/macro";

function WelcomeBanner({ userName }) {
  return (
    <div>
      <h1>
        <Trans>Welcome to our platform</Trans>
      </h1>
      <p>
        <Trans>
          Hello {userName}, check out your <a href="/dashboard">dashboard</a> to
          get started.
        </Trans>
      </p>
    </div>
  );
}

Le hook useLingui

Pour les chaînes en dehors du JSX - messages d'alerte, libellés aria, valeurs d'attributs ou tout code impératif - utilisez le hook de macro useLingui avec des littéraux de gabarit tagués :

import { useLingui } from "@lingui/react/macro";

function NotificationButton() {
  const { t } = useLingui();

  const showAlert = () => {
    alert(t`Your changes have been saved.`);
  };

  return (
    <button onClick={showAlert} aria-label={t`Save changes`}>
      <Trans>Save</Trans>
    </button>
  );
}

IDs de messages et descriptions

Lingui prend en charge deux approches pour l'identification des messages : les IDs générés automatiquement (dérivés du contenu du message source) et les IDs explicites (clés définies par le développeur). Les deux approches fonctionnent avec les fichiers PO.

import { Trans } from "@lingui/react/macro";

// Auto-generated ID (from message content)
<Trans>Welcome to our platform</Trans>

// Explicit ID (developer-defined key)
<Trans id="nav.welcome">Welcome to our platform</Trans>

Ajout de contexte pour les traducteurs et l'IA

Utilisez la prop comment sur n'importe quelle macro pour ajouter une description. Ce commentaire est extrait dans le fichier PO en tant que note pour le traducteur, fournissant un contexte critique sur l'endroit et la manière dont le message apparaît.

import { Trans } from "@lingui/react/macro";

<Trans comment="Shown on the homepage hero section above the fold">
  Start building with confidence
</Trans>

Pluralisation

Lingui utilise ICU MessageFormat pour la pluralisation, qui prend en charge toutes les catégories plurielles CLDR. La macro Plural facilite la gestion des différentes formes plurielles directement dans JSX :

• Utilisez le composant Plural avec value, one, other et les formes exactes optionnelles (_0, _2, etc.).
• Le caractère de remplacement # est automatiquement remplacé par la valeur plurielle.
• l10n.dev génère toutes les formes plurielles requises pour chaque langue cible - y compris les langues complexes comme l'arabe (6 formes), le russe et le polonais - sans intervention manuelle.

import { Plural } from "@lingui/react/macro";

function CartSummary({ itemCount }) {
  return (
    <p>
      <Plural
        value={itemCount}
        _0="Your cart is empty"
        one="You have # item in your cart"
        other="You have # items in your cart"
      />
    </p>
  );
}

Initialisation à l'exécution

Après avoir extrait et compilé vos messages, configurez l'instance i18n et enveloppez votre application dans le I18nProvider.

Configuration du module i18n

Créez un module i18n qui charge dynamiquement les catalogues de messages compilés. Le plugin Vite de Lingui permet l'importation directe des fichiers PO, qui sont compilés à la volée pendant le développement :

// src/i18n.ts
import { i18n } from "@lingui/core";

export async function loadCatalog(locale: string) {
  const { messages } = await import(`./locales/${locale}/messages.po`);
  i18n.load(locale, messages);
  i18n.activate(locale);
}

// Initialize with default locale
loadCatalog("en");

export default i18n;

Configuration de I18nProvider

Enveloppez toute votre application avec I18nProvider pour rendre les traductions disponibles pour tous les composants via le contexte React :

// src/App.tsx
import { I18nProvider } from "@lingui/react";
import { i18n } from "./i18n";

function App() {
  return (
    <I18nProvider i18n={i18n}>
      <YourAppContent />
    </I18nProvider>
  );
}

Changement de langue à l'exécution

Changer de langue est simple : chargez le nouveau catalogue, activez la locale et React re-rend automatiquement tout le contenu traduit. Voici un composant de changement de langue complet :

import { useState } from "react";
import { loadCatalog } from "./i18n";
import { Trans } from "@lingui/react/macro";

const LANGUAGES = {
  en: "English",
  fr: "Français",
  de: "Deutsch",
  ja: "日本語",
  es: "Español",
};

function LanguageSwitcher() {
  const [currentLocale, setCurrentLocale] = useState("en");

  const handleChange = async (locale: string) => {
    await loadCatalog(locale);
    setCurrentLocale(locale);
  };

  return (
    <select
      value={currentLocale}
      onChange={(e) => handleChange(e.target.value)}
    >
      {Object.entries(LANGUAGES).map(([code, name]) => (
        <option key={code} value={code}>
          {name}
        </option>
      ))}
    </select>
  );
}

Flux de travail d'extraction et de compilation

La CLI de Lingui fournit deux commandes clés qui forment le cœur de votre flux de travail de traduction : extract pour extraire les messages du code source vers les catalogues PO, et compile pour convertir les fichiers PO en modules JavaScript optimisés pour la production.

# Extract messages from source code into PO catalogs
npx lingui extract

# Translate your PO files (manually, with a TMS, or with AI)

# Compile PO catalogs into optimized JS modules for production
npx lingui compile

1. Extraction : Scanne vos fichiers sources et crée ou met à jour les catalogues PO avec tous les messages traduisibles.
2. Traduction : Remplissez les champs msgstr dans vos fichiers PO - manuellement, avec un TMS ou automatiquement avec la traduction assistée par IA.
3. Compilation : Convertit les catalogues PO en modules JS légers chargés à l'exécution. Seuls les messages traduits sont inclus.

Support complet des fichiers PO dans l10n.dev

l10n.dev offre un support natif pour les fichiers PO, ce qui en fait le compagnon idéal pour les projets Lingui.js. Téléversez votre catalogue PO source et recevez des fichiers traduits avec précision :

• Format PO natif : Téléversez directement vos fichiers PO - l10n.dev lit les entrées msgid, les traduit et renvoie des fichiers PO correctement formatés avec les valeurs msgstr appropriées.
• Conscient de l'ICU MessageFormat : Les caractères de remplacement ({name}), les balises indexées (<0>), les formes plurielles et les expressions de sélection sont correctement préservés dans toutes les traductions.
• Traduction IA consciente du contexte : Les commentaires du traducteur (#.) et le contexte du message (msgctxt) sont utilisés par notre IA pour produire des traductions plus précises et adaptées au contexte.
• Génération de pluriels : Toutes les formes plurielles CLDR requises sont générées pour chaque langue cible. Les langues avec des règles plurielles complexes (arabe, russe, polonais) sont gérées automatiquement.
• Mises à jour par lots et incrémentielles : Traduisez des catalogues entiers à la fois ou utilisez l'option --update pour traduire uniquement les messages nouveaux et modifiés, en préservant les traductions existantes.

Automatisez les traductions avec npm

Utilisez le package npm ai-l10n pour traduire vos catalogues PO Lingui depuis la ligne de commande ou dans le cadre d'un pipeline CI/CD. Installez une fois, puis traduisez vers n'importe quel nombre de langues en une seule commande.

# Install the CLI
npm install ai-l10n

# Translate your source PO file to multiple languages
npx ai-l10n translate src/locales/en/messages.po \
  --languages fr,de,ja,zh-CN,es,ko

Intégration dans votre processus de build

Intégrez ai-l10n directement dans votre processus de build Lingui afin que les traductions soient toujours à jour. Combinez l'extraction, la traduction et la compilation dans un seul flux de travail.

Via les scripts package.json

Ajoutez extract, translate et compile en tant que scripts et enchaînez-les. Le script i18n exécute le pipeline complet ; utilisez-le en pré-build pour garantir que les traductions sont toujours à jour avant la mise en ligne.

{
  "scripts": {
    "extract": "lingui extract",
    "compile": "lingui compile",
    "translate": "ai-l10n translate src/locales/en/messages.po --languages fr,de,ja,zh-CN,es,ko --update",
    "i18n": "npm run extract && npm run translate && npm run compile",
    "prebuild": "npm run i18n",
    "build": "vite build",
    "dev": "vite"
  }
}

Via Makefile

Si votre équipe utilise Make, déclarez l'extraction, la traduction et la compilation comme des cibles distinctes avec des dépendances appropriées :

LANGUAGES = fr,de,ja,zh-CN,es,ko

extract:
	npx lingui extract

translate:
	npx ai-l10n translate src/locales/en/messages.po --languages $(LANGUAGES) --update

compile:
	npx lingui compile

i18n: extract translate compile

dev: i18n
	npx vite

build: i18n
	npx vite build

Pour l'intégration CI/CD, les mises à jour incrémentielles, la traduction par lots sur plusieurs fichiers et des exemples de flux de travail GitHub Actions, consultez le Guide d'automatisation de la localisation.

Extension VS Code

L'extension VS Code l10n.dev intègre la traduction de fichiers PO directement dans votre éditeur. Traduisez vos catalogues Lingui sans quitter VS Code.

Comment ça fonctionne dans VS Code :

1. Ouvrez votre fichier PO source (par ex. src/locales/en/messages.po) dans l'éditeur.
2. Faites un clic droit dans l'éditeur et sélectionnez "Translate..." (fonctionne aussi avec les fichiers PO).
3. Choisissez une ou plusieurs langues cibles (par ex. français, japonais, allemand).
4. L'extension crée des fichiers PO traduits dans les dossiers de locale correspondants, prêts à être compilés.

Commencez à localiser votre application React avec Lingui

Prêt à atteindre des utilisateurs mondiaux ? Traduisez vos fichiers PO Lingui directement dans l'espace de travail l10n.dev, automatisez avec la CLI npm, ou traduisez directement dans VS Code :