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

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

Warum Lingui.js für i18n?

Lingui.js hebt sich von anderen JavaScript-i18n-Bibliotheken durch die Kombination aus Entwicklererfahrung, Leistung und professionellen Übersetzungs-Workflows ab:

• Sauber und lesbar: Schreiben Sie Übersetzungen natürlich mithilfe von JSX-Makros – die Bibliothek kompiliert diese im Hintergrund in das ICU-MessageFormat.
• Universell: @lingui/core funktioniert in jedem JavaScript-Projekt, während @lingui/react React-spezifische Komponenten hinzufügt, einschließlich der Unterstützung für React Server Components (RSC).
• Vollständige Rich-Text-Unterstützung: Verwenden Sie React-Komponenten nahtlos innerhalb übersetzbarer Nachrichten – Links, Fettdruck, Icons und beliebiges JSX werden vollständig unterstützt.
• PO-Dateiformat: Verwendet das branchenübliche PO-Format, das von nahezu 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 benötigte Daten werden zur Kompilierzeit entfernt.
• Bereit für KI-Übersetzungen: Die Nachrichtenbeschreibungen und Kontextkommentare von Lingui geben KI-Übersetzern die Informationen, die sie für präzise, kontextbezogene Übersetzungen benötigen.

Installation

Installieren Sie die Kernpakete und Entwicklungstools von Lingui. Die Runtime-Pakete (@lingui/core und @lingui/react) werden in der Produktion benötigt, während CLI, Vite-Plugin und Babel-Makro nur für die Entwicklung gedacht 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 (zur Definition von Locales und Katalogpfaden) und die Konfiguration Ihres Build-Tools (zur Aktivierung der Compile-Time-Makros).

Lingui-Konfiguration

Erstellen Sie eine lingui.config.js-Datei im Stammverzeichnis Ihres Projekts. Hier definieren Sie Ihre Quell-Locale, Ziel-Locales, den Speicherort für PO-Kataloge und das Katalogformat. Das PO-Format ist die Standardeinstellung und die 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 und dem Babel-Makro hinzu. Dies ermöglicht die Nachrichten-Transformation zur Kompilierzeit und die On-the-fly-Katalog-Kompilierung:

// 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 aus dem GNU-gettext-System stammt. Lingui verwendet PO als Standard-Katalogformat, da es weltweit von Übersetzungstools, TMS-Plattformen und professionellen Übersetzern breit unterstützt wird.

• Lesbar: Selbst große Übersetzungsdateien bleiben durch klare msgid/msgstr-Paare menschenlesbar.
• Übersetzerkommentare: Unterstützt #.-Kommentare, die Kontextbeschreibungen direkt an Übersetzer weitergeben.
• Quellverweise: Jede Nachricht enthält #: file:line-Kommentare, die genau zeigen, wo sie in Ihrem Code 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 nahezu jedem Translation Management System (TMS), CAT-Tool und 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-MessageFormat-Syntax, 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 Locale. Die 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 zum Markieren von Nachrichten: JSX-Makros für Komponenteninhalt und den useLingui-Hook für imperative Zeichenfolgen. Beide sind Compile-Time-Makros, die optimierte Ausgaben erzeugen.

Das Trans-Makro

Umschließen Sie beliebige JSX-Inhalte mit dem Trans-Makro, um sie übersetzbar zu machen. Variablen, HTML-Elemente und React-Komponenten werden vollständig unterstützt – das Makro wandelt sie automatisch in das ICU-MessageFormat 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 – wie Alert-Nachrichten, Aria-Labels, Attributwerte oder imperativen 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 für die Nachrichtenidentifizierung: automatisch generierte IDs (abgeleitet vom Quellnachrichteninhalt) und explizite IDs (entwicklerdefinierte 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 bei jedem Makro, um eine Beschreibung hinzuzufügen. Dieser Kommentar wird als Übersetzerhinweis in die PO-Datei extrahiert und liefert kritischen 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-MessageFormat 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, etc.).
• 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>
  );
}

Runtime-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-Setup

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 on-the-fly 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-Setup

Umschließen Sie Ihre gesamte App mit dem I18nProvider, um Übersetzungen über den React-Kontext für alle Komponenten 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 Locale, 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>
  );
}

Workflow für Extraktion und Kompilierung

Die CLI von Lingui bietet zwei Schlüsselbefehle, 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 werden einbezogen.

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: PO-Dateien direkt hochladen – l10n.dev liest msgid-Einträge, übersetzt sie und schreibt ordnungsgemäß formatierte PO-Dateien mit korrekten msgstr-Werten zurück.
• ICU-MessageFormat-bewusst: Platzhalter ({name}), indizierte Tags (<0>), Pluralformen und Select-Ausdrücke bleiben über alle Übersetzungen hinweg korrekt erhalten.
• Kontextbewusste KI-Übersetzung: Übersetzerkommentare (#.) und Nachrichtenkontext (msgctxt) werden von unserer KI verwendet, um präzisere, kontextbezogene Übersetzungen zu erstellen.
• Pluralgenerierung: Alle erforderlichen CLDR-Pluralformen werden für jede Zielsprache generiert. Sprachen mit komplexen Pluralregeln (Arabisch, Russisch, Polnisch) werden automatisch gehandhabt.
• Batch- und inkrementelle Updates: Ü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.

Automatisieren Sie Übersetzungen mit npm

Verwenden Sie das npm-Paket ai-l10n, 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

Binden Sie ai-l10n direkt in Ihren Lingui-Build-Prozess ein, 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 diese. Das i18n-Skript führt die gesamte Pipeline aus; verwenden Sie es im prebuild, um sicherzustellen, dass Übersetzungen vor dem Release 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 Updates, Batch-Übersetzung über mehrere Dateien und Beispiele für GitHub-Actions-Workflows, siehe den Leitfaden zur Lokalisierungsautomatisierung.

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 Locale-Ordnern, bereit zum Kompilieren.

Starten Sie die Lokalisierung Ihrer React-App mit Lingui

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