Provider und Hooks
Stelle eine Sprache und einen Katalog bereit, kombiniere gemeinsame und seitenspezifische Nachrichten und wechsle die Sprache, ohne Rendering-Eingaben zu vermischen.
LingoProvider stellt einem Komponenten-Teilbaum eine Sprache und einen Katalog bereit. useLingo() greift auf den nächstgelegenen Provider zu und gibt die Nachrichten- und Formatierungsmethoden für diese Eingaben zurück.
Diese Rendering-Beispiele setzen React 19 voraus. Folge der Installationsanleitung im React-Schnellstart, bevor du den Provider verwendest.
import { LingoProvider, useLingo, type Messages } from "@lingo.dev/react";
function SaveButton() {
const l = useLingo();
return (
<button type="submit">
{l.text("Save", { context: "Submit changes to account settings" })}
</button>
);
}
export function Settings({ messages }: { messages: Messages }) {
return (
<LingoProvider locale="fr" messages={messages}>
<SaveButton />
</LingoProvider>
);
}Lade die französischen Nachrichten, bevor du Settings renderst. Der Provider erwartet Messages, eine Record<string, string>, und keinen Dateipfad, kein Promise und keine Liste geparster JSONC-Einträge. Beim Laden des Katalogs entsteht diese Map.
Provider-Eingaben #
| Prop | Vorgaben |
|---|---|
locale | Erforderliche Zeichenfolge für Diagnosemeldungen bei der Nachrichtensuche sowie für Grammatik und Formatierung. |
messages | Optionale Map mit Zeichenfolgen als Werten und Hashes als Schlüsseln; Standardwert: {}. |
children | Erforderlicher ReactNode-Teilbaum. |
Auch mit einem leeren Katalog steht dem Teilbaum eine sprachabhängige Formatierung zur Verfügung; Nachrichtenaufrufe verwenden dann ihre Quellvorlagen. Der Provider selbst legt weder die Dokumentsprache noch die Schreibrichtung fest.
Rufe useLingo in einer Komponente unterhalb des Providers auf. Ein Aufruf außerhalb eines Providers löst eine Ausnahme aus. Gibt dieselbe Komponente einen Provider zurück, liegt ihr Hook dadurch nicht unterhalb dieses Providers. Trenne deshalb den Provider-Wrapper von der Komponente, die den Hook nutzt.
Gemeinsame und seitenspezifische Nachrichten kombinieren #
Verschachtelte Provider mit derselben Zeichenfolge für die Sprache führen ihre Maps zusammen. Einträge des untergeordneten Providers überschreiben Einträge mit demselben Schlüssel im übergeordneten Provider. Die übrigen Einträge des übergeordneten Providers bleiben verfügbar. So kann eine Route seitenspezifische Nachrichten hinzufügen, ohne gemeinsame Navigationsnachrichten zu wiederholen.
<LingoProvider locale="fr" messages={sharedMessages}>
<LingoProvider locale="fr" messages={pageMessages}>
<SettingsPage />
</LingoProvider>
</LingoProvider>Hier sind sharedMessages und pageMessages bereits geladene französische Maps. Wechselt die Sprache des inneren Providers zu es, wird er unabhängig: Fehlen spanische Nachrichten, wird auf den Quelltext zurückgegriffen, statt französischen Text zu übernehmen. Verglichen wird die exakte Zeichenfolge für die Sprache. Achte deshalb in der gesamten Anwendung auf eine einheitliche Schreibweise.
Sprache und Katalog gemeinsam wechseln #
Speichere die Rendering-Eingabe als Wertepaar, etwa { locale: "fr", messages: frenchMessages }. Lade die nächste Map und ersetze anschließend das Wertepaar mit einer einzigen Zustandsaktualisierung. Änderst du nur die Sprache, kann französischer Text weiterhin mit spanischer Zahlenformatierung angezeigt werden.
Lass während des Ladens des nächsten Katalogs die Darstellung mit dem bisherigen Wertepaar sichtbar oder zeige einen Ladezustand an – je nach Interaktionsdesign der Anwendung. Verwende in Anwendungen mit Routing die passende Anleitung für Next Pages oder TanStack; die jeweiligen Sprachumschalter laden die neuen Eingaben unterschiedlich.
Ein Lingo-Objekt ohne Hook erstellen #
Verwende createLingo(locale: string, messages?: Messages): Lingo, wenn eine Funktion außerhalb einer React-Komponente eine Zeichenfolge benötigt:
import { createLingo } from "@lingo.dev/react";
const l = createLingo("en-US");
const title = l.text("Account settings", { context: "Settings page title" });
const percentage = l.percent(0.125, { maximumFractionDigits: 1 });Der Aufruf gibt Account settings zurück und formatiert das Verhältnis in dieser Sprache als 12.5%. Dabei wird weder eine Übersetzungsanfrage gestellt noch ein Provider abonniert. Erstelle ein neues Objekt, wenn sich die Sprache oder die Nachrichten ändern.
Sowohl createLingo als auch useLingo stellen locale, direction, script und region bereit. Verwende Sprachmetadaten, um Dokumentattribute zu setzen, und behalte während der Hydrierung dieselben Eingaben bei.