Der Sprachwechsel ermöglicht es Nutzerinnen und Nutzern, die bevorzugte locale für die Inhalte Ihrer Anwendung festzulegen. GT Next bietet mehrere Ansätze – vom einfachen programmatischen Umschalten bis hin zu vollständig URL‑basiertem Routing mit Middleware.

Verfügbare Methoden

• Programmgesteuert: useSetLocale-Hook für benutzerdefinierte Steuerelemente
• Vorgefertigte UI: <LocaleSelector>-Komponente mit Dropdown
• Eigene UI: useLocaleSelector-Hook zum Erstellen benutzerdefinierter Selektoren
• URL-basiert: Middleware-Routing für locale in URL-Pfaden

Verwenden des useSetLocale-Hooks

Der useSetLocale-Hook ist ein clientseitiger Hook, mit dem Sie die Sprache Ihrer App ändern können:

import { useSetLocale } from 'gt-next/client';

export default function MyComponent() {
  const setLocale = useSetLocale();

  return <button onClick={() => setLocale('en')}>Sprache ändern</button>;
}

Übergeben Sie einfach die gewünschte locale als Argument an die vom Hook zurückgegebene Funktion.

Verwendung der <LocaleSelector>-Komponente

Die <LocaleSelector>-Komponente stellt ein sofort einsatzbereites Dropdown bereit, das automatisch alle konfigurierten locales anzeigt:

import { LocaleSelector } from 'gt-next/client';

export default function MyComponent() {
  return <LocaleSelector />;
}

Diese Komponente übernimmt automatisch:

• Zeigt alle konfigurierten locales für Ihr Projekt an
• Zeigt locales in ihren jeweiligen Sprachbezeichnungen an
• Handhabt die Umschaltlogik
• Behält die aktuelle Auswahl bei

Verwenden des useLocaleSelector-Hooks

Wenn Sie eine eigene, maßgeschneiderte Locale-Auswahlkomponente erstellen möchten, verwenden Sie useLocaleSelector:

import { useLocaleSelector } from 'gt-next/client';

function CustomLocaleSelector() {
  const { 
    locale,              // Aktuelle aktive Locale (z. B. 'en', 'es')
    locales,             // Array der Locales, die Ihr Projekt unterstützt ['en', 'es', 'fr']
    setLocale,           // Funktion zum Ändern der Locale: setLocale('es')
    getLocaleProperties  // Funktion zum Abrufen von Anzeigeinformationen für eine Locale
  } = useLocaleSelector();
  
  if (!locales?.length) return null;
  
  return (
    <select 
      value={locale || ''} 
      onChange={(e) => setLocale(e.target.value)}
    >
      {locales.map((loc) => {
        const props = getLocaleProperties(loc);
        return (
          <option key={loc} value={loc}>
            {props.nativeNameWithRegionCode} {/* z. B. „English (US)“, „Español (ES)“ */}
          </option>
        );
      })}
    </select>
  );
}

URL-basierter Sprachwechsel

Für SEO und eine bessere UX kannst du die locale mithilfe von Middleware-Routing in deine URLs aufnehmen. Weitere Informationen zu diesem Ansatz findest du im Middleware-Guide:

/en/products  → Englische Produktseite  
/es/products  → Spanische Produktseite
/fr/products  → Französische Produktseite

Dieser Ansatz bietet SEO-Vorteile, direkte Links zu Sprachversionen und teilbare, lokalisierte Links.

Wichtige Hinweise

Nur Client Components

Alle Sprachwechsel-Hooks und -Komponenten müssen in Client Components verwendet werden, die mit „use client“ gekennzeichnet sind:

'use client';
import { useSetLocale } from 'gt-next/client';

function LanguageSwitcher() {
  const setLocale = useSetLocale();
  // ... component logic
}

Voraussetzung: GTProvider

Sprachumschalt-Komponenten müssen innerhalb eines <GTProvider> verwendet werden:

// ✅ Korrekt
<GTProvider>
  <LanguageSwitcher />
</GTProvider>

// ❌ Falsch – außerhalb des Providers
<LanguageSwitcher />

Nächste Schritte

• Middleware-Leitfaden – URL-basiertes Sprachrouting
• Leitfaden für dynamische Inhalte – Übersetzung von Inhalten zur Laufzeit
• API-Referenzen:
  • useSetLocale Hook
  • <LocaleSelector> Component