Sprache wechseln

Alpha

Der Lingo.dev Compiler befindet sich in der Alpha-Phase. Er ist instabil, wird nicht für den Produktionseinsatz empfohlen und APIs können sich zwischen Releases ändern.

Der Lingo.dev Compiler stellt den Hook useLingoContext() bereit, mit dem Sie die aktive Sprache zur Laufzeit auslesen und ändern können. Verwenden Sie ihn, um Sprachumschalter, sprachsensitive Komponenten oder jede andere UI zu erstellen, die auf die Sprachpräferenz der Nutzer reagiert.

useLingoContext()-Hook#

Der Hook gibt ein Objekt mit der aktuellen Sprache und einer Funktion zum Ändern dieser Sprache zurück:

tsx

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

const { locale, setLocale } = useLingoContext();

Eigenschaft	Typ	Beschreibung
`locale`	`string`	Der aktive Sprachcode (z. B. `"en"`, `"es"`).
`setLocale`	`(locale: string) => void`	Legt die neue Sprache fest. Löst standardmäßig die Persistenz und ein Neuladen der Seite aus.

Beispiel für einen Sprachumschalter#

Eine Sprachumschalter-Komponente als Dropdown:

tsx

"use client"; // Required for Next.js App Router

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

const localeLabels: Record<string, string> = {
  en: "English",
  es: "Espanol",
  de: "Deutsch",
  fr: "Francais",
  ja: "日本語",
};

export function LanguageSwitcher() {
  const { locale, setLocale } = useLingoContext();

  return (
    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
      {Object.entries(localeLabels).map(([code, label]) => (
        <option key={code} value={code}>
          {label}
        </option>
      ))}
    </select>
  );
}

In Next.js muss der Sprachumschalter eine Client Component ("use client") sein, da er einen React-Hook verwendet.

Was passiert, wenn setLocale aufgerufen wird#

Sprache wird gespeichert

Standardmäßig wird die neue Sprache in einem Cookie namens locale mit einer Gültigkeitsdauer von 1 Jahr gespeichert. So bleibt die Einstellung über Seitenneuladungen und Browser-Neustarts hinweg erhalten.

Seite wird neu geladen

Die Seite wird neu geladen, damit alle Komponenten mit der neuen Sprache neu gerendert werden. Server Components laden Übersetzungen für die neue Sprache auf dem Server, und Client Components erhalten das aktualisierte Wörterbuch.

Nachfolgende Anfragen verwenden die neue Sprache

Beim nächsten Laden der Seite liest der Compiler die gespeicherte Sprache aus und liefert die passenden Übersetzungen aus.

Persistenzoptionen#

Der standardmäßige Persistenzmechanismus basiert auf Cookies und wird über localePersistence konfiguriert:

{
  localePersistence: {
    type: "cookie",
    config: {
      name: "locale",       // Cookie name
      maxAge: 31536000,     // 1 year in seconds
    },
  },
}

Option	Standard	Beschreibung
`type`	`"cookie"`	Persistenzmechanismus.
`config.name`	`"locale"`	Cookie-Name.
`config.maxAge`	`31536000`	Cookie-Lebensdauer in Sekunden.

Benutzerdefinierte Persistenz#

Für URL-basiertes Sprachrouting, localStorage oder benutzerdefinierte headerbasierte Erkennung erstellen Sie benutzerdefinierte Sprach-Resolver. Der Export persistLocale in Ihrem Client-Resolver steuert, was passiert, wenn setLocale aufgerufen wird:

// .lingo/locale-resolver.client.ts
export function resolveLocale(): string {
  return localStorage.getItem("locale") || "en";
}

export function persistLocale(locale: string): void {
  localStorage.setItem("locale", locale);
  window.location.reload();
}

Unter Custom Locale Resolvers finden Sie vollständige Beispiele für URL-basierte, Cookie-basierte und headerbasierte Muster.

Sprache lesen, ohne zu wechseln#

Wenn Sie die aktuelle Sprache für die Anzeige oder bedingtes Rendering benötigen, ohne einen Umschalter bereitzustellen, verwenden Sie denselben Hook:

tsx

"use client";

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

export function LocaleBadge() {
  const { locale } = useLingoContext();
  return <span>{locale.toUpperCase()}</span>;
}

Nächste Schritte#

Custom Locale Resolvers

URL-basierte, localStorage- und headerbasierte Persistenz

Konfigurationsreferenz

localePersistence-Optionen

Next.js-Integration

Verhalten von Server Components und Client Components

Vite + React

Clientseitiger Sprachwechsel