Nachrichtenkataloge extrahieren und laden

Quellnachrichten extrahieren, eine übersetzte JSONC-Datei abrufen und mit den zugehörigen Quellmetadaten eine Zuordnung für die Laufzeit erstellen.

Eine Komponente enthält die Quellnachricht und ihren Kontext. Die Extraktion sammelt diese Aufrufe in einer übersetzbaren Datei. Beim Laden werden die übersetzten Werte wieder den Schlüsseln der Komponente zugeordnet. Diese Anleitung führt die erste Begrüßung durch diesen dateibasierten Workflow und erstellt die Messages-Zuordnung, die ein Provider benötigt.

Die Quelle extrahieren #

Installiere die CLI und die Loader-Abhängigkeiten in der Anwendung:

sh
npm install --save-dev @lingo.dev/cli@latest
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npx lingo extract --src src --source-locale en

Die Extraktion läuft lokal und benötigt keinen API-Schlüssel. Standardmäßig schreibt sie locales/en.jsonc und lingo.d.ts. Explizit gesetzte Flags für --out und --types haben Vorrang vor den konfigurierten Werten für i18n.messagesPath und i18n.typesPath. Diese haben wiederum Vorrang vor den Standardwerten. Eine Pages-Anwendung mit Aufrufen außerhalb von src verwendet ihr tatsächliches Verzeichnis, etwa --src pages.

Sieh dir den Eintrag für die Begrüßung an. Sein Wert enthält die vollständige englische Vorlage; der Schlüssel ergibt sich aus Quelle und Kontext. Die vorangestellten Kommentare halten mit @context die Bedeutung und mit @src die Position im Quellcode fest. @orphan kennzeichnet einen zuvor extrahierten Eintrag, der nicht mehr aktiv ist. Führe eine Prüfung dieser Änderungen durch, bevor du Übersetzungen anforderst.

Den ausgewählten Katalog übersetzen #

Initialisiere bei einer Anwendung ohne Lingo.dev-Konfiguration genau diese Datei und Spanisch als Zielsprache. Authentifiziere dich anschließend und verknüpfe eine Lokalisierungs-Engine:

sh
npx lingo init --source en --targets es --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link

Du benötigst Zugriff auf eine aktivierte Lokalisierungs-Engine und ein ausreichendes Nutzungskontingent für dein Konto. CLI-Authentifizierung erläutert die Zugangsdaten für unbeaufsichtigte Ausführungen.

Falls .lingo/config.json bereits vorhanden ist, behalte die bestehende Verknüpfung und die anderen Dateieinträge bei. Ergänze oder aktualisiere den Eintrag, der locales/en.jsonc auswählt, und stelle sicher, dass die Quellsprache des Projekts en ist. Schließe bei einem bestehenden Ausgangsstand zunächst die regulären Aktualisierungen für die vorhandenen Zielsprachen mit npx lingo push --wait ab. Schließe alle ausstehenden Prüfungen ab, behebe alle Fehler und sieh dir die abgerufenen Änderungen an, bevor du es zu targetLocales hinzufügst. Halte die Quellrevision während des anschließenden Nachladens fehlender Dateien unverändert. Eine Sprache hinzufügen erläutert diese Reihenfolge. Verwende für die Konfigurationsänderung nicht init --force: Dadurch werden die Dateieinträge neu erstellt, wobei erweiterte Optionen verloren gehen können. Konfiguration beschreibt die vollständige Struktur.

Fordere für das neue Projekt oder nach Abschluss dieser Vorbereitung für ein bestehendes Projekt die fehlenden Zieldateien an und warte, bis sie abgerufen wurden. Ändere die Zieldateien nicht, solange dieser Befehl wartet, da der Download lokale Änderungen überschreiben kann:

sh
npx lingo push --backfill-missing --wait

Sieh dir nach Abschluss der Ausführung locales/es.jsonc an. Kläre alle gemeldeten Prüfungs- oder Fehlerzustände, bevor du die Ausgabe als vollständig betrachtest. Führe bei späteren Änderungen an der Quelle die Extraktion erneut aus und verwende npx lingo push --wait. Das Nachladen dient dazu, fehlende Dateien abzurufen, nicht dazu, ein vorhandenes Ziel regulär zu aktualisieren.

Quellmetadaten zusammen mit der Zielrevision aufbewahren #

Der allgemeine JSONC-Übersetzungs-Workflow behält die @orphan-Markierungen der Quelle im Ziel bei, entfernt aber die @context- und @src-Kommentare. Aus einer Zieldatei allein kann ein Loader nicht ermitteln, zu welcher Seite eine Nachricht gehörte.

Bewahre die extrahierte Quelldatei aus derselben Revision wie die Zieldatei auf. Wähle die aktiven Einträge dieser Quelle aus und verknüpfe ihre Schlüssel mit den übersetzten Werten der Zieldatei. So werden entfernte Nachrichten ausgeschlossen, und die Auswahl nach Quellroute bleibt möglich. Fehlende Zielschlüssel bleiben ausgespart, sodass die Laufzeit auf die Quelle zurückgreifen kann.

Einen Katalog im Rohformat parsen #

Erstelle src/catalog.ts mit diesem anwendungseigenen Loader:

ts
import { parse, type ParseError } from "jsonc-parser";
import { getActiveEntries, readLocaleFile, type LocaleEntry } from "@lingo.dev/spec";
import type { Messages } from "@lingo.dev/react";

function readStringCatalog(raw: string) {
  const errors: ParseError[] = [];
  const value: unknown = parse(raw, errors, { allowTrailingComma: true });
  if (
    errors.length > 0 ||
    value === null ||
    typeof value !== "object" ||
    Array.isArray(value) ||
    Object.values(value).some((entry) => typeof entry !== "string")
  ) {
    throw new Error("Expected a flat JSONC object with string values");
  }
  return readLocaleFile(raw);
}

export function loadMatchedMessages(
  sourceJsonc: string,
  targetJsonc: string,
  include: (entry: LocaleEntry) => boolean = () => true,
): Messages {
  const active = getActiveEntries(readStringCatalog(sourceJsonc).entries);
  const target = new Map(readStringCatalog(targetJsonc).entries.map((entry) => [entry.key, entry.value]));
  return Object.fromEntries(
    active.filter(include).flatMap((entry) => {
      const value = target.get(entry.key);
      return value === undefined ? [] : [[entry.key, value]];
    }),
  );
}

readLocaleFile parst JSONC-Syntax und Metadaten, validiert aber nicht die Datenstruktur zur Laufzeit. Trotz des deklarierten Eintragstyps akzeptiert es Arrays und Werte, die keine Zeichenfolgen sind. Bei primitiven Werten oder null auf der obersten Ebene gibt es keine Einträge zurück. Die erste Funktion oben weist diese Strukturen zurück, bevor die Werte den Renderer erreichen können. Beide Funktionen arbeiten lokal und führen keine Ein-/Ausgabe aus.

Lade in einer Vite-Anwendung die Dateien als Rohtext in dem Modul, das den Provider versorgt:

ts
import source from "../locales/en.jsonc?raw";
import target from "../locales/es.jsonc?raw";
import { loadMatchedMessages } from "./catalog";

export const spanishMessages = loadMatchedMessages(source, target);

Dabei wird vorausgesetzt, dass das Modul direkt unter src liegt und die Client-Typen von Vite eingebunden sind. Übergib spanishMessages als messages mit locale="es". Die Begrüßung sollte nun die abgerufene spanische Vorlage verwenden und weiterhin {name} durch Ana ersetzen. Sieh dir den tatsächlichen Wortlaut an und teste den Umgang mit fehlenden Einträgen. Das Laden einer Datei und die Beurteilung ihrer sprachlichen Qualität sind voneinander unabhängig.

Nur die Quelleinträge auswählen, die eine Route benötigt #

Das optionale include-Prädikat wird vor der Verknüpfung auf aktive Quelleinträge angewendet. Ein Seiten-Loader kann mit entry.metadata.src seine eigenen Aufrufe und gemeinsam genutzte Komponenten einbeziehen. Nimm diese Auswahl anhand der Quelle vor, in der die Metadaten noch vorhanden sind. Stelle Quelle und Ziel beim Deployment gemeinsam bereit, damit die Routenauswahl nicht auf Schlüssel einer anderen Revision zurückgreift.

Die Next-Pages-Anleitung enthält ein vollständiges Routenprädikat. Die TanStack-Anleitung verwendet diesen Loader für ihren Anfragekatalog. Die integrierten Loader beider Ansätze können Dateien mit Metadaten filtern. Keiner von beiden verknüpft jedoch automatisch kommentarfreie Zieldateien mit Quellmetadaten.

Referenz der Spec-Hilfsfunktionen #

ExportVerhalten
readLocaleFile(content): LocaleFileParst JSONC einschließlich abschließender Kommas und vorangestellter Metadaten-Blockkommentare; bei Syntaxfehlern wird eine Ausnahme ausgelöst.
getActiveEntries(entries): LocaleEntry[]Behält Einträge bei, deren metadata.orphan nicht als wahr ausgewertet wird.
LocaleFile{ entries: LocaleEntry[] }.
LocaleEntry{ key: string; value: string; metadata: EntryMetadata }.
EntryMetadataOptional: context, src und orphan.
computeKey(source, context?)Gemeinsame normalisierte Identität aus Quelle und Kontext, die auch von React exportiert wird.
buildIcuPlural(forms)Gibt bekannte Kardinalkategorien in kanonischer Reihenfolge aus.
buildIcuSelect(forms)Gibt Alternativen mit sortierten Schlüsseln aus.

Die ICU-Builder akzeptieren Datensätze mit Zeichenfolgenwerten; die React-Typen für plural und select ergänzen die jeweils erforderliche other-Form. Der resultierende Laufzeitkatalog ist eine einfache Messages-Zuordnung, kein LocaleFile.

Bestehende Ressourcen mit Schlüsseln, Dokumente und statische TypeScript-Sprachmodule verwenden ihre eigenen Format-Handler statt dieser Extraktionsanleitung. Die Beispielprojekte zeigen diese Strukturen neben React-Anwendungen.