Nachrichtenaufrufe auf Typkorrektheit prüfen

Generiere und binde Deklarationen ein, die Quelltexte, Kontexte und Nachrichtenwerte schon beim Bearbeiten auf Typkorrektheit prüfen.

Ein Nachrichtenaufruf kann in TypeScript gültig sein und trotzdem den falschen Katalogeintrag anfordern. Ein geänderter Kontext oder ein Tippfehler in einem Platzhalter kann dazu führen, dass Quelltext oder {name} auf dem Bildschirm sichtbar bleibt. Die Extraktion generiert Deklarationen, die die bekannten Quellnachrichten in das Typsystem der Anwendung einbinden.

Deklaration generieren und einbinden #

Führe nach der Installation der CLI Folgendes aus:

sh
npx lingo extract --src src --source-locale en

Die Standardausgabedateien sind locales/en.jsonc und lingo.d.ts. Füge lingo.d.ts zur bestehenden tsconfig-Include-Liste der Anwendung hinzu, falls noch kein Muster diese Datei erfasst. Lass die übrigen Einträge unverändert:

json
{
  "include": ["src", "lingo.d.ts"]
}

Führe die übliche Typprüfung der Anwendung aus. Eine Deklaration außerhalb des Compiler-Projekts schränkt keine Aufrufe ein. Wenn die Extraktion --types oder i18n.typesPath verwendet, binde stattdessen den tatsächlichen Ausgabepfad ein.

Was die generierte Schnittstelle bedeutet #

Die Datei erweitert LingoMessages um Quelltexte und ihre Optionen. Dieses Beispiel zeigt die generierte Struktur:

ts
export {};

declare module "@lingo.dev/react" {
  interface LingoMessages {
    "Hello, {name}.": {
      values: { name: string | number };
      context: "Greeting on the account dashboard";
    };
    "Save": {
      context: "Submit settings" | "Bookmark an article";
    };
  }
}

Generiere diese Datei neu, statt das Beispiel von Hand zu pflegen. Die Begrüßung erfordert jetzt values.name und ihren extrahierten Kontext. Save akzeptiert jeden der beiden erfassten Kontexte. Ein nicht aufgeführter Quelltext erfüllt die Typvorgabe von MessageKey nicht.

Ohne generierte Einträge ist LingoMessages leer und MessageKey erlaubt beliebige Zeichenfolgen. Sobald Einträge vorhanden sind, wird MessageKey zum Union-Typ seiner Zeichenfolgeschlüssel. Das Laufzeitverhalten bleibt unverändert: Diese Typvorgaben gelten für l.text und l.rich während der Bearbeitung.

Typen mit dem Quelltext synchron halten #

Führe die Extraktion erneut aus, wenn du Text, Kontext oder Platzhalter geändert hast. Entfernte Nachrichten werden zu verwaisten Einträgen und von der Generierung ausgeschlossen. Für Einträge ohne Kontext wird keine Signatur generiert, es sei denn, ein anderer aktiver Eintrag für denselben Quelltext liefert einen Kontext. Mehrere Kontexte für denselben Quelltext bilden einen Union-Typ.

So stellst du fest, ob alles aktuell ist, ohne Dateien zu schreiben:

sh
npx lingo extract --src src --source-locale en --check

Dabei werden sowohl JSONC als auch die Deklarationen mit der aktuellen Extraktion verglichen. Das ist eine lokale Prüfung, keine Übersetzungsanfrage. Führe sie zusammen mit der Typprüfung aus, damit eine veraltete Deklaration nicht unbemerkt den Nachrichtenbestand von gestern vorgibt.

Werttypen und Abdeckung #

Der Generator erkennt ICU-Argumente auf oberster Ebene. Er verwendet number für Plural-, Ordinal- und Zahlenargumente, string für Auswahlargumente, Date | number für Datums- und Zeitargumente und string | number für einfache Platzhalter. Er erkennt nicht jeden Platzhalter, der innerhalb eines Pluralzweigs verschachtelt ist. Teste die Werte dieser Zweige daher ausdrücklich.

Die generierten Typvorgaben für Quelltexte gelten für text und rich. Die Hilfsfunktionen plural und select behalten ihre eigenen Signaturen für Formen und Optionen. Aufrufe für formatierten Text ergänzen eine optionale Tag-Zuordnung, doch die Deklarationen kontrollieren nicht die Platzierung der Tags im Zieltext.

Typen zeigen dir, ob ein Aufruf die Vorgaben des extrahierten Quelltexts erfüllt. Rendering-Tests zeigen dir, ob die geladene Übersetzung diese Werte verwenden kann. Nutze beides: Auch bei einem gültigen Aufruf kann der Katalogeintrag fehlen oder der ICU-Ausdruck im Zieltext fehlerhaft sein.