useLingo

useLingo() ist der Weg, über den Komponenten auf die Runtime zugreifen. Es liest das nächstgelegene <LingoProvider> und gibt das aktive Lingo-Objekt zurück — rufe es pro Komponente einmal auf, behalte die Referenz und nutze die Methoden, die du brauchst.

tsx

import { useLingo } from "@lingo.dev/react";

function Greeting() {
  const l = useLingo();
  return <p>{l.text("Hello", { context: "Hero heading" })}</p>;
}

Wird es außerhalb eines Providers aufgerufen, löst es einen Fehler aus. In Tests musst du den Render also entsprechend wrappen — selbst mit messages: {}, wenn Übersetzungen im Test keine Rolle spielen.

`l.text(source, options)` — einfache Strings#

Der Standardaufruf im Alltag. Gibt einen übersetzten String zurück — oder den Quelltext, wenn es für die aktuelle Sprache keine Übersetzung gibt.

tsx

l.text("Save", { context: "Form button" });
// → "Speichern" (de) / "Save" (en, fallback)

Interpolation#

{placeholder}-Segmente werden durch Werte aus options.values ersetzt.

tsx

l.text("Welcome back, {name}!", {
  values: { name: user.firstName },
  context: "Dashboard greeting",
});

Fehlende Werte werden unverändert als {name} gerendert — praktisch, um Bugs während der Entwicklung zu erkennen. Achte aber darauf, dass deine Tests das gerenderte Ergebnis prüfen, damit keine leeren Werte unbemerkt durchrutschen.

Wenn der Quelltext ICU-Syntax enthält#

Wenn der Quelltext Marker für Plural / Select / Zahl / Datum enthält, erweitert sich die Runtime automatisch — ganz ohne zusätzliche API. Einen benutzerfreundlichen Wrapper findest du unter Plurale und Select.

`l.rich(source, options)` — React-Teilbäume#

Wenn der übersetzte Text React-Komponenten enthält (Links, Fettungen, ein <Icon/>), verwende l.rich. Der Übersetzungs-String enthält Platzhalter-Tags wie <link>...</link>; jedem Tag ordnest du einen Renderer zu.

tsx

l.rich("Click <link>here</link> for {topic}", {
  tags: {
    link: (children) => <a href="/help">{children}</a>,
  },
  values: { topic: "details" },
  context: "Footer help link",
});
// → <>Click <a href="/help">here</a> for details</>

Auch selbstschließende Tags funktionieren:

tsx

l.rich("Loading <spinner/>...", {
  tags: { spinner: () => <Spinner /> },
  context: "Inline loading state",
});

Tags ohne Renderer fallen auf den Rohtext zurück — so ist ein fehlendes Tag in der Entwicklung sichtbar, statt stillschweigend unterzugehen.

Setze Markup nicht direkt in übersetzte Strings. l.rich gibt es, damit Übersetzer neutrale Platzhalter (<link>) statt <a href="..."> sehen, die sie sonst wortwörtlich beibehalten müssten — und dabei oft kaputtmachen. Definiere den Renderer in deinem Code, nicht in der Sprachdatei.

Sprachmetadaten auf `l`#

Zusätzlich zur Übersetzung stellt das Objekt Folgendes bereit:

Eigenschaft	Typ	Hinweise
`l.locale`	`string`	Genau der Wert, den du an `LingoProvider` übergeben hast. BCP-47.
`l.direction`	`"ltr"` \| `"rtl"`	Berechnet über `Intl.Locale.textInfo` plus Fallback-Liste für RTL-Sprachen.
`l.script`	`string` \| `undefined`	Wird, wenn möglich, abgeleitet (`"Latn"`, `"Cyrl"`, `"Arab"`, …).
`l.region`	`string` \| `undefined`	Aus BCP-47 abgeleitet (`"US"`, `"DE"`, `"SA"`, …).

Praktisch für Layout-Entscheidungen:

tsx

const l = useLingo();
return <div dir={l.direction}>...</div>;

Formatierungsmethoden#

l bringt außerdem num, currency, percent, date, time, datetime, relative, list, displayName, sort, segment, fileSize, compact, unit mit — die vollständige Übersicht findest du unter Formatierung. Das sind schlanke Wrapper um native Intl.*-Formatter, abgestimmt auf l.locale.

Außerhalb von React#

useLingo funktioniert nur innerhalb von Komponenten. Für Utilities, Route-Loader oder Server-Code erzeugst du dasselbe Objekt direkt:

import { createLingo } from "@lingo.dev/react";

const l = createLingo("es", messages);
l.text("Hello", { context: "Email subject" });

Es hat dieselbe Lingo-Struktur, ganz ohne Provider. LingoProvider selbst verwendet intern createLingo.

tsx

import { useLingo } from "@lingo.dev/react";

function Greeting() {
  const l = useLingo();
  return <p>{l.text("Hello", { context: "Hero heading" })}</p>;
}