Lingui.js-Lokalisierung: PO-Dateien, React i18n & Automatisierung

Lingui.js ist ein leichtgewichtiges und dennoch leistungsstarkes Internationalisierungs-Framework (i18n) für JavaScript- und React-Anwendungen. Es verwendet branchenübliche PO-Dateien (Portable Object) für Übersetzungskataloge, leistungsstarke Makros zur Kompilierzeit für eine saubere Entwicklererfahrung und erzeugt optimierte Bundles unter 2 kB. Dieser Leitfaden deckt alles ab, von der Projekteinrichtung bis zu PO-Datei-Workflows, Pluralisierung und der Automatisierung von Übersetzungen mit l10n.dev.

Warum Lingui.js für i18n?

Lingui.js zeichnet sich unter JavaScript-i18n-Bibliotheken durch seine Kombination aus Entwicklererfahrung, Leistung und professionellen Übersetzungs-Workflows aus:

• Sauber und lesbar: Schreiben Sie Übersetzungen auf natürliche Weise mit JSX-Makros – die Bibliothek kompiliert sie im Hintergrund in das ICU-Nachrichtenformat.
• Universell: @lingui/core funktioniert in jedem JavaScript-Projekt, während @lingui/react React-spezifische Komponenten einschließlich Unterstützung für React Server Components (RSC) hinzufügt.
• Vollständige Rich-Text-Unterstützung: Verwenden Sie React-Komponenten nahtlos innerhalb übersetzbarer Nachrichten – Links, Fettdruck, Symbole und jedes JSX werden vollständig unterstützt.
• PO-Dateiformat: Verwendet das branchenübliche PO-Format, das von praktisch jedem Übersetzungstool, TMS und professionellen Übersetzer-Workflow unterstützt wird.
• Leichtgewichtig und optimiert: Die Kernbibliothek ist unter 2 kB gzipped, React-Komponenten fügen nur 1,3 kB hinzu. Nicht wesentliche Daten werden zur Kompilierzeit entfernt.
• Bereit für KI-Übersetzungen: Die Nachrichtenbeschreibungen und Kontextkommentare von Lingui geben KI-Übersetzern die Informationen, die sie benötigen, um genaue, kontextbewusste Übersetzungen zu erstellen.

Installation

Installieren Sie die Kernpakete und Entwicklungstools von Lingui. Die Laufzeitpakete (@lingui/core und @lingui/react) werden in der Produktion benötigt, während das CLI, das Vite-Plugin und das Babel-Makro nur für die Entwicklung bestimmt sind:

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

Konfiguration

Lingui erfordert zwei Konfigurationsdateien: die Lingui-Konfiguration (Definition von Sprachversionen und Katalogpfaden) und Ihre Build-Tool-Konfiguration (zur Aktivierung von Makros zur Kompilierzeit).

Lingui-Konfiguration

Erstellen Sie eine lingui.config.js-Datei in Ihrem Projektstammverzeichnis. Dies definiert Ihre Quell-Sprachversion, Zielsprachversionen, Speicherort für PO-Kataloge und das Katalogformat. Das PO-Format ist die Standard- und empfohlene Wahl:

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

Vite-Konfiguration

Wenn Sie Vite verwenden, fügen Sie das Lingui-Plugin zusammen mit dem React-Plugin mit dem Babel-Makro hinzu. Dies ermöglicht die Nachrichten-Transformation zur Kompilierzeit und die Katalogkompilierung im laufenden Betrieb:

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

Das PO-Dateiformat

PO (Portable Object) ist das branchenübliche Übersetzungsdateiformat, das vom GNU-gettext-System stammt. Lingui verwendet PO als Standard-Katalogformat, da es von Übersetzungstools, TMS-Plattformen und professionellen Übersetzern weltweit weithin unterstützt wird.

• Lesbar: Selbst große Übersetzungsdateien bleiben mit klaren msgid/msgstr-Paaren für Menschen lesbar.
• Übersetzerkommentare: Unterstützt #. Kommentare, die Kontextbeschreibungen direkt an Übersetzer weitergeben.
• Quellreferenzen: Jede Nachricht enthält #: Datei:Zeile-Kommentare, die genau zeigen, wo sie in Ihrer Codebasis verwendet wird.
• Kontextunterstützung: Verwenden Sie msgctxt, um identische Zeichenfolgen zu unterscheiden, die in verschiedenen Kontexten unterschiedliche Bedeutungen haben.
• Universelle Tool-Unterstützung: Kompatibel mit praktisch jedem Übersetzungsmanagementsystem (TMS), CAT-Tool und jeder Lokalisierungsplattform.

Extrahierte PO-Datei (Quellnachrichten)

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

Übersetzte PO-Datei (Französisch)

Nach der Übersetzung wird jedes msgstr mit der lokalisierten Version gefüllt. Lingui bewahrt die ICU-Nachrichtenformatsyntax, indizierte Tags für React-Komponenten und Platzhaltervariablen über alle Übersetzungen hinweg.

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

Projektstruktur

Organisieren Sie Ihre PO-Kataloge in einem locales-Verzeichnis mit einem Unterordner pro Sprachversion. Das Lingui-CLI erstellt und aktualisiert diese Dateien während der Extraktion automatisch. Kompilierte JS-Module werden zur Build-Zeit generiert und sollten nicht manuell bearbeitet werden.

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

React-Komponenten übersetzen

Lingui bietet zwei Hauptansätze für die Kennzeichnung von Nachrichten: JSX-Makros für Komponenteninhalt und den useLingui-Hook für imperative Zeichenfolgen. Beide sind Makros zur Kompilierzeit, die optimierte Ausgaben erzeugen.

Das Trans-Makro

Umschließen Sie jeden JSX-Inhalt mit dem Trans-Makro, um ihn übersetzbar zu machen. Variablen, HTML-Elemente und React-Komponenten werden vollständig unterstützt – das Makro wandelt sie automatisch in das ICU-Nachrichtenformat mit indizierten Tags um.

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

Der useLingui-Hook

Für Zeichenfolgen außerhalb von JSX – Warnmeldungen, Aria-Labels, Attributwerte oder beliebiger imperativer Code – verwenden Sie den useLingui-Makro-Hook mit tagged template literals:

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

Nachrichten-IDs und Beschreibungen

Lingui unterstützt zwei Ansätze zur Nachrichtenidentifikation: automatisch generierte IDs (abgeleitet vom Quellnachrichteninhalt) und explizite IDs (vom Entwickler definierte Schlüssel). Beide Ansätze funktionieren mit PO-Dateien.

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>

Kontext für Übersetzer und KI hinzufügen

Verwenden Sie den comment-Prop für jedes Makro, um eine Beschreibung hinzuzufügen. Dieser Kommentar wird als Übersetzerhinweis in die PO-Datei extrahiert und bietet entscheidenden Kontext darüber, wo und wie die Nachricht erscheint.

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

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

Pluralisierung

Lingui verwendet das ICU-Nachrichtenformat für die Pluralisierung, das alle CLDR-Pluralkategorien unterstützt. Das Plural-Makro macht es einfach, verschiedene Pluralformen direkt in JSX zu handhaben:

• Verwenden Sie die Plural-Komponente mit value, one, other und optionalen exakten Formen (_0, _2 usw.).
• Der #-Platzhalter wird automatisch durch den Pluralwert ersetzt.
• l10n.dev generiert alle erforderlichen Pluralformen für jede Zielsprache – einschließlich komplexer Sprachen wie Arabisch (6 Formen), Russisch und Polnisch – ohne manuellen Eingriff.

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

Laufzeit-Initialisierung

Nachdem Sie Ihre Nachrichten extrahiert und kompiliert haben, richten Sie die i18n-Instanz ein und umschließen Sie Ihre App mit dem I18nProvider.

i18n-Modul-Einrichtung

Erstellen Sie ein i18n-Modul, das kompilierte Nachrichtenkataloge dynamisch lädt. Das Lingui-Vite-Plugin ermöglicht den direkten Import von PO-Dateien, die während der Entwicklung im laufenden Betrieb kompiliert werden:

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

I18nProvider-Einrichtung

Umschließen Sie Ihre gesamte App mit I18nProvider, um Übersetzungen für alle Komponenten über React-Kontext verfügbar zu machen:

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

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

Sprachwechsel zur Laufzeit

Das Wechseln von Sprachen ist unkompliziert: Laden Sie den neuen Katalog, aktivieren Sie die Sprachversion, und React rendert automatisch alle übersetzten Inhalte neu. Hier ist eine vollständige Sprachwechsler-Komponente:

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

Extraktions- und Kompilierungs-Workflow

Das Lingui-CLI bietet zwei Hauptbefehle, die den Kern Ihres Übersetzungs-Workflows bilden: extract, um Nachrichten aus dem Quellcode in PO-Kataloge zu ziehen, und compile, um PO-Dateien in optimierte JavaScript-Module für die Produktion zu konvertieren.

# 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. Extrahieren: Scannt Ihre Quelldateien und erstellt oder aktualisiert PO-Kataloge mit allen übersetzbaren Nachrichten.
2. Übersetzen: Füllen Sie die msgstr-Felder in Ihren PO-Dateien aus – manuell, mit einem TMS oder automatisch mit KI-gestützter Übersetzung.
3. Kompilieren: Konvertiert PO-Kataloge in leichtgewichtige JS-Module, die zur Laufzeit geladen werden. Nur übersetzte Nachrichten sind enthalten.

Vollständige PO-Unterstützung in l10n.dev

l10n.dev bietet native Unterstützung für PO-Dateien und ist damit der perfekte Begleiter für Lingui.js-Projekte. Laden Sie Ihren Quell-PO-Katalog hoch und erhalten Sie präzise übersetzte Dateien zurück:

• Natives PO-Format: Laden Sie PO-Dateien direkt hoch – l10n.dev liest msgid-Einträge, übersetzt sie und schreibt ordnungsgemäß formatierte PO-Dateien mit korrekten msgstr-Werten zurück.
• ICU-Nachrichtenformat-bewusst: Platzhalter ({name}), indizierte Tags (<0>), Pluralformen und Auswahlausdrücke bleiben über alle Übersetzungen hinweg korrekt erhalten.
• Kontextbewusste KI-Übersetzung: Übersetzerkommentare (#.) und Nachrichtenkontext (msgctxt) werden von unserer KI verwendet, um genauere, kontextbewusste Übersetzungen zu erstellen.
• Plural-Generierung: Alle erforderlichen CLDR-Pluralformen werden für jede Zielsprache generiert. Sprachen mit komplexen Pluralregeln (Arabisch, Russisch, Polnisch) werden automatisch behandelt.
• Batch- und inkrementelle Aktualisierungen: Übersetzen Sie ganze Kataloge auf einmal oder verwenden Sie das --update-Flag, um nur neue und geänderte Nachrichten zu übersetzen, wobei bestehende Übersetzungen erhalten bleiben.

Übersetzungen mit npm automatisieren

Verwenden Sie das ai-l10n npm-Paket, um Ihre Lingui-PO-Kataloge über die Befehlszeile oder als Teil einer CI/CD-Pipeline zu übersetzen. Einmal installieren, dann in einem einzigen Befehl in beliebig viele Sprachen übersetzen.

# 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

Integration in Ihren Build-Prozess

Verknüpfen Sie ai-l10n direkt mit Ihrem Lingui-Build-Prozess, damit Übersetzungen immer auf dem neuesten Stand sind. Kombinieren Sie Extraktion, Übersetzung und Kompilierung in einem einzigen Workflow.

Über package.json-Skripte

Fügen Sie extract, translate und compile als Skripte hinzu und verketten Sie sie. Das i18n-Skript führt die gesamte Pipeline aus; verwenden Sie es in prebuild, um sicherzustellen, dass Übersetzungen vor dem Versand immer aktuell sind.

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

Über Makefile

Wenn Ihr Team Make verwendet, deklarieren Sie Extraktion, Übersetzung und Kompilierung als separate Ziele mit entsprechenden Abhängigkeiten:

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

Für CI/CD-Integration, inkrementelle Übersetzungen, Batch-Übersetzung über mehrere Dateien und Beispiele für GitHub Actions-Workflows, siehe den Lokalisierungsautomatisierungs-Leitfaden.

VS Code-Erweiterung

Die l10n.dev VS Code-Erweiterung bringt die PO-Datei-Übersetzung direkt in Ihren Editor. Übersetzen Sie Ihre Lingui-Kataloge, ohne VS Code zu verlassen.

So funktioniert es in VS Code:

1. Öffnen Sie Ihre Quell-PO-Datei (z. B. src/locales/en/messages.po) im Editor.
2. Klicken Sie mit der rechten Maustaste in den Editor und wählen Sie "Translate..." (funktioniert auch mit PO-Dateien).
3. Wählen Sie eine oder mehrere Zielsprachen (z. B. Französisch, Japanisch, Deutsch).
4. Die Erweiterung erstellt übersetzte PO-Dateien in den entsprechenden Sprachversionsordnern, bereit zur Kompilierung.

Beginnen Sie mit der Lokalisierung Ihrer React-App mit Lingui

Bereit, globale Nutzer zu erreichen? Übersetzen Sie Ihre Lingui-PO-Dateien direkt im l10n.dev-Arbeitsbereich, automatisieren Sie mit dem npm CLI oder übersetzen Sie direkt in VS Code: