Localizzazione Lingui.js: file PO, i18n 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 sotto i 2 kB. Questa guida copre tutto, dalla configurazione del progetto ai flussi di lavoro dei file PO, alla pluralizzazione e all'automazione delle traduzioni con l10n.dev.

Perché Lingui.js per i18n?

Lingui.js si distingue tra le librerie i18n 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 utilizzando le macro JSX: la libreria le compila in formato messaggio ICU sotto il cofano.
• Universale: @lingui/core funziona in qualsiasi progetto JavaScript, mentre @lingui/react aggiunge componenti specifici per React, incluso il supporto per React Server Components (RSC).
• Supporto completo per rich-text: Utilizza i componenti React all'interno dei messaggi traducibili senza problemi: collegamenti, testo in grassetto, icone e qualsiasi 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 di traduzione.
• 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 AI: Le descrizioni dei messaggi e i commenti di contesto di Lingui forniscono ai traduttori AI le informazioni necessarie per produrre traduzioni accurate e consapevoli del contesto.

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 Lingui (che definisce le lingue e i percorsi del catalogo) e la configurazione del tuo strumento di build (per abilitare le macro in fase di compilazione).

Configurazione Lingui

Crea un file lingui.config.js nella root del tuo progetto. Questo definisce la tua 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 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 i file di traduzione di grandi dimensioni rimangono leggibili dall'uomo con chiare coppie msgid/msgstr.
• Commenti del traduttore: Supporta i commenti #. che trasmettono le descrizioni del contesto direttamente ai traduttori.
• Riferimenti sorgente: Ogni messaggio include commenti #: file:line che mostrano esattamente dove viene utilizzato nel tuo codice.
• Supporto contesto: Usa msgctxt per disambiguare stringhe identiche che hanno significati diversi in contesti diversi.
• Supporto strumenti universale: Compatibile con praticamente ogni sistema di gestione della traduzione (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 del formato messaggio ICU, 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 lingua. La CLI Lingui crea e aggiorna automaticamente questi file durante l'estrazione. I moduli JS compilati vengono generati al momento della 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
└── ...

Traduzione dei componenti React

Lingui fornisce due approcci principali per contrassegnare i messaggi: macro JSX per il contenuto dei componenti e l'hook useLingui per le 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 formato messaggio ICU 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 le 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 messaggio 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>

Aggiunta di contesto per traduttori e AI

Usa la prop comment su qualsiasi macro per aggiungere una descrizione. Questo commento viene estratto nel file PO come nota del 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 il formato messaggio ICU per la pluralizzazione, che supporta tutte le categorie plurali CLDR. La macro Plural rende facile gestire diverse forme plurali direttamente in JSX:

• Usa il componente Plural con valore, 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 arabo (6 forme), russo e 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 runtime

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

Configurazione 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 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 tutto il contenuto tradotto. Ecco un componente commutatore di lingua completo:

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

Workflow di estrazione e compilazione

La CLI di Lingui fornisce due comandi chiave che costituiscono 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 tuoi 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 AI.
3. Compile: Converte i cataloghi PO in moduli JS leggeri che vengono caricati a runtime. Sono inclusi solo i messaggi tradotti.

Supporto PO completo 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 correttamente formattati con valori msgstr corretti.
• Consapevolezza del formato messaggio ICU: Segnaposti ({name}), tag indicizzati (<0>), forme plurali ed espressioni select vengono preservati correttamente in tutte le traduzioni.
• Traduzione AI consapevole del contesto: I commenti del traduttore (#.) e il contesto del messaggio (msgctxt) vengono utilizzati dalla nostra AI per produrre traduzioni più accurate e consapevoli del contesto.
• Generazione plurale: 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 e 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 CI/CD pipeline. Installa una volta, quindi 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 tuo 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 della distribuzione.

{
  "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 appropriate:

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 essere compilati.

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 all'interno di VS Code: