Localizzazione con Lingui.js: file PO, i18n in React e automazione

Lingui.js è un framework di internazionalizzazione (i18n) leggero ma potente per applicazioni JavaScript e React. Utilizza file PO (Portable Object) standard del settore per i cataloghi di traduzione, potenti macro in fase di compilazione per un'esperienza di sviluppo pulita e produce bundle ottimizzati inferiori a 2 kB. Questa guida copre tutto, dalla configurazione del progetto ai flussi di lavoro dei file PO, la pluralizzazione e l'automazione delle traduzioni con l10n.dev.

Perché scegliere Lingui.js per l'i18n?

Lingui.js si distingue tra le librerie i18n per JavaScript per la sua combinazione di esperienza di sviluppo, prestazioni e flussi di lavoro di traduzione professionali:

• Pulito e leggibile: Scrivi le traduzioni in modo naturale usando le macro JSX: la libreria le compila internamente nel formato ICU MessageFormat.
• Universale: @lingui/core funziona in qualsiasi progetto JavaScript, mentre @lingui/react aggiunge componenti specifici per React, incluso il supporto per i React Server Components (RSC).
• Supporto completo per il rich-text: Usa i componenti React all'interno dei messaggi traducibili senza problemi: link, testo in grassetto, icone e qualsiasi elemento JSX sono pienamente supportati.
• Formato file PO: Utilizza il formato PO standard del settore, supportato da praticamente ogni strumento di traduzione, TMS e flusso di lavoro professionale.
• Leggero e ottimizzato: La libreria principale è inferiore a 2 kB gzipped, i componenti React aggiungono solo 1,3 kB. I dati non essenziali vengono rimossi in fase di compilazione.
• Pronto per le traduzioni IA: Le descrizioni dei messaggi e i commenti di contesto di Lingui forniscono ai traduttori IA le informazioni necessarie per produrre traduzioni accurate e contestualizzate.

Installazione

Installa i pacchetti principali e gli strumenti di sviluppo di Lingui. I pacchetti runtime (@lingui/core e @lingui/react) sono necessari in produzione, mentre la CLI, il plugin Vite e la macro Babel sono solo per lo sviluppo:

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

Configurazione

Lingui richiede due file di configurazione: la configurazione di Lingui (che definisce le lingue e i percorsi dei cataloghi) e la configurazione del tuo strumento di build (per abilitare le macro in fase di compilazione).

Configurazione di Lingui

Crea un file lingui.config.js nella root del progetto. Questo definisce la lingua sorgente, le lingue di destinazione, dove archiviare i cataloghi PO e il formato del catalogo. Il formato PO è la scelta predefinita e consigliata:

// 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 }),
});

Configurazione di Vite

Se usi Vite, aggiungi il plugin Lingui insieme al plugin React con la macro Babel. Ciò abilita la trasformazione dei messaggi in fase di compilazione e la compilazione del catalogo al volo:

// 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(),
  ],
});

Il formato file PO

PO (Portable Object) è il formato di file di traduzione standard del settore, derivante dal sistema GNU gettext. Lingui utilizza PO come formato di catalogo predefinito perché è ampiamente supportato da strumenti di traduzione, piattaforme TMS e traduttori professionisti in tutto il mondo.

• Leggibile: Anche file di traduzione di grandi dimensioni rimangono leggibili dall'uomo con chiare coppie msgid/msgstr.
• Commenti per i traduttori: Supporta i commenti #. che trasmettono descrizioni di contesto direttamente ai traduttori.
• Riferimenti al sorgente: Ogni messaggio include commenti #: file:riga che mostrano esattamente dove viene utilizzato nel codice.
• Supporto al contesto: Usa msgctxt per distinguere stringhe identiche che hanno significati diversi in contesti differenti.
• Supporto universale: Compatibile con praticamente ogni sistema di gestione delle traduzioni (TMS), strumento CAT e piattaforma di localizzazione.

File PO estratto (messaggi sorgente)

#: 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 ""

File PO tradotto (francese)

Dopo la traduzione, ogni msgstr viene popolato con la versione localizzata. Lingui preserva la sintassi ICU MessageFormat, i tag indicizzati per i componenti React e le variabili segnaposto in tutte le traduzioni.

#: 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}}"

Struttura del progetto

Organizza i tuoi cataloghi PO all'interno di una directory locales con una sottocartella per ogni lingua. La CLI di Lingui crea e aggiorna automaticamente questi file durante l'estrazione. I moduli JS compilati vengono generati durante la build e non dovrebbero essere modificati manualmente.

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
└── ...

Tradurre i componenti React

Lingui fornisce due approcci principali per contrassegnare i messaggi: macro JSX per il contenuto dei componenti e l'hook useLingui per stringhe imperative. Entrambi sono macro in fase di compilazione che producono output ottimizzato.

La macro Trans

Avvolgi qualsiasi contenuto JSX nella macro Trans per renderlo traducibile. Variabili, elementi HTML e componenti React sono pienamente supportati: la macro li trasforma automaticamente in ICU MessageFormat con tag indicizzati.

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>
  );
}

L'hook useLingui

Per stringhe al di fuori di JSX (messaggi di avviso, etichette aria, valori di attributi o qualsiasi codice imperativo), usa l'hook macro useLingui con template letterali taggati:

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>
  );
}

ID dei messaggi e descrizioni

Lingui supporta due approcci per l'identificazione dei messaggi: ID generati automaticamente (derivati dal contenuto del messaggio sorgente) e ID espliciti (chiavi definite dallo sviluppatore). Entrambi gli approcci funzionano con i file 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>

Aggiungere contesto per traduttori e IA

Usa la prop comment su qualsiasi macro per aggiungere una descrizione. Questo commento viene estratto nel file PO come nota per il traduttore, fornendo un contesto critico su dove e come appare il messaggio.

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

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

Pluralizzazione

Lingui utilizza ICU MessageFormat per la pluralizzazione, che supporta tutte le categorie plurali CLDR. La macro Plural facilita la gestione di diverse forme plurali direttamente in JSX:

• Usa il componente Plural con i valori one, other e forme esatte opzionali (_0, _2, ecc.).
• Il segnaposto # viene sostituito automaticamente con il valore plurale.
• l10n.dev genera tutte le forme plurali richieste per ogni lingua di destinazione, incluse lingue complesse come l'arabo (6 forme), il russo e il polacco, senza intervento manuale.

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>
  );
}

Inizializzazione del runtime

Dopo aver estratto e compilato i messaggi, configura l'istanza i18n e avvolgi la tua app nell'I18nProvider.

Configurazione del modulo i18n

Crea un modulo i18n che carica dinamicamente i cataloghi di messaggi compilati. Il plugin Lingui Vite abilita l'importazione diretta dei file PO, che vengono compilati al volo durante lo sviluppo:

// 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;

Configurazione di I18nProvider

Avvolgi l'intera app con I18nProvider per rendere le traduzioni disponibili a tutti i componenti tramite il contesto React:

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

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

Cambio lingua a runtime

Cambiare lingua è semplice: carica il nuovo catalogo, attiva la lingua e React esegue automaticamente il re-render di tutti i contenuti tradotti. Ecco un componente completo per il cambio lingua:

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>
  );
}

Flusso di lavoro di estrazione e compilazione

La CLI di Lingui fornisce due comandi chiave che formano il nucleo del tuo flusso di lavoro di traduzione: extract per estrarre i messaggi dal codice sorgente nei cataloghi PO e compile per convertire i file PO in moduli JavaScript ottimizzati per la produzione.

# 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. Extract: Scansiona i file sorgente e crea o aggiorna i cataloghi PO con tutti i messaggi traducibili.
2. Translate: Compila i campi msgstr nei tuoi file PO, manualmente, con un TMS o automaticamente con la traduzione basata su IA.
3. Compile: Converte i cataloghi PO in moduli JS leggeri caricati a runtime. Vengono inclusi solo i messaggi tradotti.

Supporto completo PO in l10n.dev

l10n.dev fornisce supporto nativo per i file PO, rendendolo il compagno perfetto per i progetti Lingui.js. Carica il tuo catalogo PO sorgente e ricevi file tradotti accuratamente:

• Formato PO nativo: Carica file PO direttamente: l10n.dev legge le voci msgid, le traduce e riscrive file PO formattati correttamente con i valori msgstr corretti.
• Consapevole di ICU MessageFormat: Segnaposti ({name}), tag indicizzati (<0>), forme plurali ed espressioni select vengono preservati correttamente in tutte le traduzioni.
• Traduzione IA consapevole del contesto: I commenti del traduttore (#.) e il contesto del messaggio (msgctxt) vengono utilizzati dalla nostra IA per produrre traduzioni più accurate e contestualizzate.
• Generazione dei plurali: Tutte le forme plurali CLDR richieste vengono generate per ogni lingua di destinazione. Le lingue con regole plurali complesse (arabo, russo, polacco) vengono gestite automaticamente.
• Aggiornamenti batch e incrementali: Traduci interi cataloghi in una volta sola o usa il flag --update per tradurre solo i messaggi nuovi o modificati, preservando le traduzioni esistenti.

Automatizza le traduzioni con npm

Usa il pacchetto npm ai-l10n per tradurre i tuoi cataloghi Lingui PO dalla riga di comando o come parte di una pipeline CI/CD. Installa una volta, poi traduci in qualsiasi numero di lingue con un singolo comando.

# 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

Integrazione nel processo di build

Collega ai-l10n direttamente al tuo processo di build Lingui in modo che le traduzioni siano sempre aggiornate. Combina estrazione, traduzione e compilazione in un unico flusso di lavoro.

Tramite script package.json

Aggiungi extract, translate e compile come script e concatenali. Lo script i18n esegue l'intera pipeline; usalo in prebuild per assicurarti che le traduzioni siano sempre aggiornate prima del rilascio.

{
  "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"
  }
}

Tramite Makefile

Se il tuo team usa Make, dichiara estrazione, traduzione e compilazione come target separati con le dipendenze corrette:

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

Per l'integrazione CI/CD, aggiornamenti incrementali, traduzione batch su più file ed esempi di workflow GitHub Actions, consulta la Guida all'automazione della localizzazione.

Estensione VS Code

L'estensione VS Code di l10n.dev porta la traduzione dei file PO direttamente nel tuo editor. Traduci i tuoi cataloghi Lingui senza lasciare VS Code.

Come funziona in VS Code:

1. Apri il tuo file PO sorgente (es. src/locales/en/messages.po) nell'editor.
2. Fai clic destro nell'editor e seleziona "Translate..." (funziona anche con i file PO).
3. Scegli una o più lingue di destinazione (es. francese, giapponese, tedesco).
4. L'estensione crea file PO tradotti nelle cartelle delle lingue corrispondenti, pronti per la compilazione.

Inizia a localizzare la tua app React con Lingui

Pronto a raggiungere utenti globali? Traduci i tuoi file PO Lingui direttamente nell'area di lavoro l10n.dev, automatizza con la CLI npm o traduci direttamente dentro VS Code: