Überblick

gt-react exportiert jetzt eine t()-Funktion für die synchrone Übersetzung von Zeichenfolgen auf Modulebene im Browser.

Bisher erforderte die Übersetzung von Zeichenfolgen in gt-react React-Kontext-basierte Hooks wie useGT. Hooks funktionieren gut innerhalb von Komponenten, aber sie decken einen häufigen Anwendungsfall nicht ab: die Übersetzung von Zeichenfolgen auf Modulebene — außerhalb von React-Komponenten, vor dem Rendern und in einfachen Utility-Dateien.

t() schließt diese Lücke. Es ist eine synchrone Funktion, die Sie überall im Browser-Code aufrufen können:

import { t } from 'gt-react/browser';

const greeting = t('Hello, world!');

Keine Hooks, kein asynchroner Code, kein Komponentenbaum erforderlich.

Warum dieser Ansatz

Die Kernidee hinter diesem PR ist, zu erproben, wie sich der React-Kontext-Ansatz für Übersetzungen vermeiden lässt. Da t() außerhalb des Komponentenbaums arbeitet, ermöglicht es interessantere Muster — insbesondere Übersetzungen auf Modulebene. Zeichenfolgen können dort übersetzt werden, wo sie definiert sind, nicht dort, wo sie gerendert werden.

Das bringt einige Kompromisse mit sich:

• Nur clientseitig. t() funktioniert nur in clientseitigen React-Anwendungen. Es setzt darauf, dass Browser-Module ausgeführt werden, um Übersetzungen zu laden, bevor die App gerendert wird.
• Vollständiges Neuladen der Seite beim Sprachwechsel. Da Übersetzungen beim Laden des Moduls aufgelöst werden, erfordert das Wechseln des Gebietsschemas eine erneute Ausführung der Module — also ein vollständiges Neuladen der Seite. Sprachen lassen sich nicht während einer Sitzung per Hot-Swapping wechseln.

Auf der anderen Seite ist die Developer Experience deutlich besser. Keine in Hooks verpackten Zeichenfolgen, kein Glue-Code auf Komponentenebene, keine asynchronen Grenzen — nur ein Funktionsaufruf.

Die bestehenden React-Kontext-Ansätze (useGT, <T>, etc.) bleiben erhalten. Dies ist eine zusätzliche Option für Projekte, bei denen diese Kompromisse sinnvoll sind.

So funktioniert es

t() löst Übersetzungen synchron aus bereits im Voraus geladenen Übersetzungen auf. Diese Übersetzungen werden von bootstrap() bereitgestellt, einer neuen asynchronen Setup-Funktion, die alle Übersetzungen für das aktuelle Gebietsschema lädt, bevor Ihre App gerendert wird.

Sie müssen den Einstiegspunkt Ihrer App so ändern, dass zuerst bootstrap() ausgeführt wird. In der Regel ist das main.tsx, aber Sie können den Einstiegspunkt in Ihrer index.html ändern.

// bootstrap.tsx (neuer Einstiegspunkt)
import gtConfig from '../gt.config.json';
import { bootstrap } from 'gt-react/browser';

async function getTranslations(locale: string) {
  return import(`./_gt/${locale}.json`);
}

await bootstrap({
  ...gtConfig,
  getTranslations,
});

await import('./main.tsx');

Die Funktion getTranslations ist asynchron — sie lädt zuerst die Übersetzungen, und erst danach wird die React-App importiert und ausgeführt. So kann t() auf Modulebene verwendet werden: Wenn ein Modul t() aufruft, stehen die Übersetzungen bereits zur Verfügung.

Das funktioniert nur in clientseitigen React-Apps, weil Code auf Modulebene erneut ausgeführt wird, wenn Sie ihn im Browser laden. Und weil wir Module erneut ausführen müssen, um die übersetzten Inhalte zu ändern, ist für einen Wechsel des Gebietsschemas ein vollständiges Neuladen der Seite erforderlich.

Variablen

t() unterstützt Variableninterpolation, genau wie msg():

import { t } from 'gt-react/browser';

t('Hello, {name}!', { name: 'John' });  // → "Hola, John!"

Wo es sinnvoll ist

t() ist die richtige Wahl, wenn Sie Übersetzungen außerhalb des React-Komponentenbaums benötigen — in Konstantendateien, Hilfsfunktionen, Konfigurationsobjekten, Router-Definitionen oder überall dort, wo Code im Browser auf Modulebene ausgeführt wird.

Beachten Sie:

• Dies ist noch nicht in das übrige gt-react-System integriert. Sie müssen das oben beschriebene Bootstrap-Setup durchführen. Es handelt sich um einen eigenständigen Ansatz.
• Nur clientseitig. Für serverseitige Übersetzungen sollten Sie React-Kontext-basierte Hooks wie useGT verwenden.

Designhinweise

t() ist nur im Browser verfügbar. Wenn die Funktion auf dem Server aufgerufen wird (wo window nicht definiert ist), gibt sie eine Warnung aus und greift auf die Quellzeichenfolge zurück. Das ist beabsichtigt — für serverseitige Übersetzungen sollten die vorhandenen React-Kontext-basierten Hooks verwendet werden.

API-Referenz

In der vollständigen t()-API-Referenz finden Sie Informationen zu Parametern, Rückgabetypen und dem Setup.