LingoProvider

LingoProvider ist der React-Kontext, der die aktive Sprache und die Message-Map enthält. Binden Sie ihn einmal auf Root-Ebene Ihrer App ein — alles darin kann useLingo() aufrufen, um Strings zu übersetzen oder Metadaten zur Sprache auszulesen.

Grundlegende Verwendung#

import { LingoProvider } from "@lingo.dev/react";
import messages from "./locales/es.json";

<LingoProvider locale="es" messages={messages}>
  <App />
</LingoProvider>

Props#

Messages ist einfach Record<string, string> — dieselbe Struktur, die die CLI nach locales/<locale>.json schreibt.

Verschachtelte Provider#

Provider lassen sich verschachteln. Welche Regeln gelten, hängt davon ab, ob der verschachtelte Provider dieselbe Sprache wie der übergeordnete Provider verwendet oder eine andere.

Gleiche Sprache — Messages werden zusammengeführt#

<LingoProvider locale="es" messages={sharedMessages}>
  {/* Route-scoped messages override shared on collision; missing keys fall through to shared. */}
  <LingoProvider locale="es" messages={dashboardMessages}>
    <Dashboard />
  </LingoProvider>
</LingoProvider>

Ideal, um Bundles pro Route aufzuteilen und gleichzeitig am Root ein gemeinsames „Shell“-Set an Übersetzungen beizubehalten.

Unterschiedliche Sprachen — eigenständig#

<LingoProvider locale="es" messages={esMessages}>
  <Header />
  <LingoProvider locale="ar-SA" messages={arMessages}>
    {/* This subtree is entirely Arabic; the parent's es messages are NOT visible. */}
    <ArabicEmbed />
  </LingoProvider>
</LingoProvider>

Praktisch, wenn Sie eine einzelne Komponente in einer festen Sprache rendern möchten (ein Zitat, ein Embed, ein Vorschaubereich) innerhalb einer App, die sonst eine andere Sprache verwendet.

Sprache zur Laufzeit wechseln#

Behandeln Sie locale wie React-State — ändern Sie ihn, und jeder useLingo()-Consumer darunter rendert mit der neuen Sprache und dem neuen Message-Bag neu.

function AppRoot() {
  const [locale, setLocale] = useState("en");
  const [messages, setMessages] = useState({});

  async function switchTo(next: string) {
    const next_messages = await import(`./locales/${next}.json`);
    setLocale(next);
    setMessages(next_messages.default);
  }

  return (
    <LingoProvider locale={locale} messages={messages}>
      <LocaleSwitcher current={locale} onSelect={switchTo} />
      <App />
    </LingoProvider>
  );
}

Was Sie aus dem Kontext auslesen können#

useLingo() gibt das aktive Lingo-Objekt zurück. Zusätzlich zu text() und rich() enthält es:

• locale — der BCP-47-String, den Sie übergeben haben
• direction — "ltr" oder "rtl", berechnet über Intl.Locale.textInfo mit einer Fallback-Liste bekannter RTL-Sprachen
• script — z. B. "Latn", "Cyrl", "Arab"
• region — z. B. "US", "DE", "SA"

Das ist nützlich für bedingte Layouts (etwa das Spiegeln von Icons in RTL) oder Analytics-Tagging — ganz ohne zusätzliches Parsing.

Häufige Fehler#

• <LingoProvider> vergessen. useLingo() wirft außerhalb davon einen Fehler. Die Fehlermeldung weist Sie darauf hin, einen Provider hinzuzufügen; wenn Sie das in Tests sehen, wrappen Sie den Render-Vorgang mit einem Test-Provider mit leeren messages, damit Assertions stabil bleiben.
• Asynchron geladene Messages direkt übergeben. messages muss ein synchroner Wert sein. Lösen Sie das Promise in einer übergeordneten Komponente auf (mit Suspense oder State) und reichen Sie das Ergebnis dann nach unten weiter.
• locale wechseln, ohne messages zu aktualisieren. Der Provider geht davon aus, dass beide Props zusammenpassen — ändern Sie sie im selben useState-Update, sonst rendern Sie kurzzeitig die neue Sprache mit den alten Übersetzungen.