Eine Web-App lokalisieren

Binde übersetzte Kataloge in die Sprachauswahl, das Laden von Ressourcen und die Rendering-Kontrollen deines Frameworks ein.

Wenn deine Web-App bereits Nachrichten aus Sprachdateien rendert, behalte diesen bewährten Aufbau bei. Lingo.dev kann die Quellkataloge übersetzen, während die vorhandene Bibliothek weiterhin die Sprache auswählt, Nachrichten lädt und rendert. Setze diesen Ablauf zunächst für eine Ansicht vollständig um, bevor du den Rest der Anwendung übersetzt.

Dieser Leitfaden behandelt bestehende schlüsselbasierte Kataloge in verschiedenen Frameworks. Für Nachrichten auf Basis von Quelltext und Kontext mit @lingo.dev/react nutze den React-Schnellstart oder den Migrationsleitfaden. Die dabei extrahierten Identitäten unterscheiden sich von den Schlüsseln in einem bestehenden i18next- oder next-intl-Katalog.

Einen durchgängigen Testfall einrichten #

Wähle eine Ansicht mit einer Beschriftung, einer Nachricht mit Variablen und einer Nachricht mit Pluralformen oder Bedingungen. Rendere sie mit der vorhandenen Bibliothek in der Ausgangssprache. Behalte die Namensräume, die Interpolationssyntax und die Schlüssel für die Nachrichtenabfrage bei. Eine generische JSON-Übersetzung wandelt die Nachrichtengrammatik einer Bibliothek nicht in die einer anderen um.

Für eine bestehende react-i18next-Quelldatei unter public/locales/en/translation.json initialisiere die CLI im Stammverzeichnis des Projekts:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'public/locales/en/translation.json' --yes
lingo link

Die verknüpfte .lingo/config.json sollte so aufgebaut sein:

json
{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es"],
  "files": [{ "pattern": "public/locales/en/translation.json" }]
}

Behalte die tatsächlichen IDs der Organisation und der Lokalisierungs-Engine bei, die beim Verknüpfen erzeugt wurden. Verwende für ein anderes Framework den passenden Quellpfad aus den folgenden Abschnitten. Wähle nur Quellkataloge aus und stimme den Zielpfad auf den Loader ab. Nutze explizite Zielpfade für Verzeichnisstrukturen ohne Sprachsegment.

Übersetze fehlende Zieldateien mit:

sh
lingo push --backfill-missing --wait

Sieh dir nach Abschluss den erzeugten Katalog an und lade die Ansicht auf Spanisch. Vergleiche dieselben Variablenwerte und Pluralfälle in beiden Sprachen. Der folgende frameworkspezifische Schritt bindet diese Datei in die tatsächliche Anfrage oder den Build ein. Ein erster einfacher Push kann einen Ausgangsstand speichern, ohne fehlende Übersetzungen anzufordern.

Lass die Zieldateien unverändert, bis das Zurückschreiben ausgeführt wird. Wenn bestehende lokale Korrekturen vor Konflikten geschützt werden müssen, übermittle ohne --wait, sieh dir lingo pull --dry-run an und rufe die Ergebnisse anschließend im selben checkout ab, aus dem die Übermittlung erfolgte. Siehe Übersetzungen nach der Prüfung bewahren.

React mit react-i18next #

Behalte bei react-i18next deine bestehenden Namensräume und Aufrufe zur Nachrichtenabfrage bei. Aus einer Quelldatei unter public/locales/en/translation.json entsteht public/locales/es/translation.json. Wenn die Anwendung mehrere Namensräume verwendet, konfiguriere jede englische Quelldatei einzeln, statt ein Glob-Muster zu verwenden, das auch die erzeugten spanischen Dateien erfasst.

Sorge dafür, dass der i18next-Ressourcen-Loader die Zielsprache und den Namensraum anfordert. Nutze dann die vorhandenen useTranslation-Aufrufe, um den Testfall zu rendern. Kontrolliere die Variablenersetzung und die Konvention für Pluralschlüssel deiner installierten i18next-Version. Ein generischer JSON-Übersetzer wandelt das Pluralschema einer Bibliothek nicht in das einer anderen um. Sieh dir in einer Client-Anwendung neben dem sichtbaren Text auch die Netzwerkanfrage für die Ressource an. Ein englischer Fallback kann eine fehlende spanische Datei verbergen.

Next.js App Router mit next-intl #

Für next-intl ist messages/en.json eine gängige Quelldatei, aus der messages/es.json entsteht. Konfiguriere in deinem next-intl-Setup die Sprachermittlung zum Zeitpunkt der Anfrage und lade die passenden Nachrichten. Halte sprachabhängige Routen und Navigation mit dieser Auswahl konsistent.

Rendere den Testfall sowohl über eine direkte Anfrage in der Zielsprache als auch über die Navigation aus einer anderen Sprache. Kontrolliere serverseitig gerenderte Inhalte, die clientseitige Hydration sowie ICU-Variablen oder Pluralformen. Die Übersetzung der Nachrichtendatei allein fügt weder ein Sprachsegment im App Router noch eine Sprachauswahl hinzu. Für längere Dokumente neben diesen UI-Katalogen nutze Markdoc mit Next.js.

Next.js Pages Router mit next-i18next #

Konfiguriere bei next-i18next das Quellmuster passend zu deinem bestehenden Sprachverzeichnis und deinen Namensräumen. Wenn diese public/locales/en/common.json und public/locales/en/checkout.json sind, übersetze beide in die entsprechenden spanischen Dateien. Wenn du messages/en.json verwendest, behalte den benutzerdefinierten Loader bei, der diese Datei tatsächlich verarbeitet.

Lade die erforderlichen Namensräume über den bestehenden serverseitigen oder statischen Datenladeprozess der Seite. Teste einen direkten Aufruf der lokalisierten Seite und einen clientseitigen Routenwechsel. Stelle sicher, dass die anfänglichen Seitendaten und die Client-Laufzeit bei Sprache und Namensraum übereinstimmen. Eine übersetzte Datei auf dem Datenträger reicht nicht aus, wenn die Seite sie nie einbindet.

Vue mit vue-i18n #

vue-i18n kann Wörterbücher wie src/locales/en.json und src/locales/es.json laden. Übersetze die englische Quelldatei und registriere das spanische Wörterbuch in der bestehenden i18n-Instanz oder lade es dort dynamisch. Lege die ausgewählte Sprache dort fest, wo deine App sie bereits verwaltet.

Teste die $t- oder useI18n-Aufrufe anhand des Testfalls. Kontrolliere verschachtelte Schlüssel, Interpolation und die Syntax für Pluralnachrichten der installierten Bibliothek. Teste sowohl einen Sprachwechsel ohne Neuladen als auch einen frischen Seitenaufruf. Wenn Wörterbücher über Imports gebündelt werden, stelle sicher, dass die übersetzte Datei im Build enthalten ist.

Nuxt mit dem i18n-Modul #

Übersetze für Nuxt i18n eine Quelldatei wie locales/en.json in locales/es.json. Registriere die Sprache und die Datei in der zu deiner installierten Version passenden Modulkonfiguration. Stimme das konfigurierte Sprachverzeichnis auf den Ausgabepfad der CLI ab.

Halte dich an die sprachabhängige Routenstrategie des Projekts, statt im Übersetzungsauftrag eine zweite Strategie anzulegen. Kontrolliere serverseitiges Rendering, verzögertes Laden, lokalisierte Navigation und Metadaten auf der Testseite. Wenn du eine Zielsprache zur Übersetzungskonfiguration hinzufügst, wird sie dadurch nicht automatisch in Nuxts Sprachliste aufgenommen.

Wörterbücher für Svelte und SvelteKit #

Übersetze für svelte-i18n ein Wörterbuch wie src/lib/locales/en.json. Registriere das Zielwörterbuch oder seinen Loader für verzögertes Laden und initialisiere die ausgewählte Sprache, bevor die Komponente sie benötigt.

Rendere den Testfall über den bestehenden Übersetzungs-Store der Anwendung. Teste eine neue serverseitig gerenderte Anfrage, wenn die App SSR verwendet, und anschließend einen clientseitigen Sprachwechsel. Stelle sicher, dass der Sprachzustand zwischen Serveranfragen isoliert bleibt und das Zielwörterbuch vollständig geladen wird. Verwende eine Fallback-Ausgabe nicht als Nachweis für eine abgeschlossene Übersetzung.

Angular XLIFF #

Nutze zunächst Angulars i18n-Workflow, um Nachrichten zu markieren und zu extrahieren. Der XLIFF-Handler unterstützt XLIFF 1.2 und 2.x, einschließlich Klartext und Inline-Codes. Text innerhalb gepaarter Codes wie <g> und <pc> wird übersetzt, während ihre Struktur erhalten bleibt. Alleinstehende Codes wie <ph> bleiben geschützt. Halte die Kennungen für Nachrichten und Inline-Codes stabil und sieh dir die zurückgegebenen Platzhalter an, bevor du den Zielkatalog importierst.

Bei unterstützten Eingaben wird src/locale/en/messages.xlf auf src/locale/es/messages.xlf abgebildet. XLIFF verwendet keine Suffixersetzung von messages.en.xlf zu messages.es.xlf. Nutze das Sprachverzeichnis oder eine explizite Zielvorlage. Behalte die Nachrichtenidentitäten bei, wenn du Übersetzungen an Angular zurückgibst.

Registriere die Zieldatei in Angulars Build-Konfiguration für die Lokalisierung, erstelle das Bundle für die Zielsprache und stelle es bereit, um dir die Ansicht anzusehen. Angulars Lokalisierung zur Kompilierzeit unterscheidet sich von einem JSON-Loader zur Laufzeit: Eine Änderung der Browsersprache erstellt kein fehlendes lokalisiertes Bundle. Kontrolliere die Nachrichtenabdeckung und die Darstellung der Platzhalter, bevor du das Bundle akzeptierst.

Astro #

Übersetze für UI-Beschriftungen src/i18n/en.json in die entsprechende Zieldatei und sorge dafür, dass dein eigener Wörterbuch-Loader sie auswählt. Übersetze für Inhaltssammlungen die sprachspezifischen Markdown- oder MDX-Quelldateien und nutze den Workflow für statische Inhalte.

Konfiguriere Astros Sprachrouting unabhängig von der Übersetzung. Erstelle einen Build und rufe die erzeugten Zielrouten auf. Kontrolliere dabei die Links zwischen den Sprachversionen sowie alle clientseitigen Islands, die ihre eigenen Nachrichten laden. Eine Inhaltssammlung und das UI-Wörterbuch einer Island benötigen möglicherweise separate Eingaben.

Laravel #

Bei der Lokalisierung mit Laravel wird eine PHP-Quelldatei wie lang/en/messages.php auf lang/es/messages.php abgebildet. Behalte Array-Schlüssel und die Namen der zur Laufzeit ersetzten Platzhalter bei. Ziehe die PHP-Formatreferenz heran, bevor du Dateien auswählst, die ausführbaren Code außerhalb der unterstützten Katalogstruktur enthalten.

Lege die Sprache der Anfrage über die bestehende Middleware oder die Controller-Regeln der Anwendung fest und rendere Nachrichten mit Laravels Übersetzungshelfern. Teste Ersetzungswerte und die Auswahl von Pluralformen. Teste eine Anfrage in jeder unterstützten Sprache sowie einen Fallback-Fall. Übersetzte Dateien wählen die Sprache der Anfrage nicht aus.

Django #

Nutze Djangos Extraktions-Workflow, um locale/en/LC_MESSAGES/django.po zu erstellen, und übersetze anschließend diese Quell-PO-Datei in das Verzeichnis der Zielsprache. Behalte gettext-Nachrichtenidentitäten, Kontext und Interpolation bei. Kompiliere die übersetzte PO-Datei mit dem bestehenden gettext-Build-Schritt des Projekts in die Ressource, die Django tatsächlich lädt.

Konfiguriere Djangos Sprachauswahl und Sprachliste. Teste eine lokalisierte Anfrage über die Übersetzungs-Middleware und rendere Singular- und Pluralaufrufe. Eine PO-Datei auf dem Datenträger belegt nicht, dass ihr kompilierter Katalog aktuell ist. Die Anforderungen an die Datei findest du unter Gettext.

Rails #

Rails erkennt YAML-Dateien mit einem Sprachschlüssel auf der obersten Ebene anhand dieses Schlüssels. Wähle yaml-root-key aus und kontrolliere anschließend die Sprachkonfiguration, die Helfer und die Interpolation von Rails. Eine Rails-App lokalisieren beschreibt den vollständigen Ablauf, einschließlich nach Aufgabenbereichen getrennter Dateien, Sprachwechsel pro Anfrage und gezielter Aktualisierungen.

Wiederkehrende Übersetzungen mit Ergebnissen für die Prüfung #

Sobald die Ansicht funktioniert, füge die übrigen Quellkataloge und ihre Loader hinzu. Bewahre akzeptierte Zieldateien zusammen mit der Quellrevision und dem CLI-Lockfile auf. Für spätere Quelländerungen verwendest du lingo push --wait für die reguläre Änderungsmenge. Ein Dateimuster als Positionsargument beschränkt die Planung stattdessen auf die ausgewählten Dateien.

Wähle die Auslöser für Quelländerungen und den Weg zum Zurückschreiben über die GitHub App oder CI-Rezepte. Rezepte für GitLab, Bitbucket und GitHub Actions führen die CLI aus und benötigen einen eigenen Mechanismus zum Zurückschreiben ins Repository. Führe für die Ausgabe den Build oder die Ressourcenkontrollen des Frameworks aus und führe anschließend eine Prüfung der übersetzten Bedeutung durch. lingo check validiert nicht jedes Framework und stellt auch nicht die Vollständigkeit von PHP, PO oder XLIFF sicher.

Ein Agent kann dabei helfen, Loader zu untersuchen und Konfigurationsänderungen vorzuschlagen. Führe für diese Änderungen dieselben Kontrollen der Quellauswahl, des Builds und der gerenderten Ansicht durch, bevor du den Workflow erweiterst.