Eine Anwendung mit TanStack Start übersetzen

Anfragen mit Sprachpräfix auflösen, den passenden Katalog laden und übersetzte Seiten mit kanonischen URLs und einer Sprachauswahl rendern.

Halte Anwendungsrouten wie /about unabhängig von der Sprache, während Nutzende /en/about oder /de/about aufrufen. @lingo.dev/react-tanstack verknüpft diese URL-Regeln mit dem Anfragekontext und den Katalogen. Die Route wird weiterhin mit /about abgeglichen; die Sprache der Anfrage bestimmt die verwendeten Texte und die daraus generierten URLs.

Diese Anleitung ergänzt eine bestehende Anwendung mit TanStack Start, React 19, TanStack Router 1.170+ und Start 1.168+ um Englisch und Deutsch. Start ist als optionale Peer-Abhängigkeit deklariert, doch das Hauptmodul des Pakets importiert createIsomorphicFn von Start. Installiere Start zusammen mit dem Adapter, auch wenn eine reine Router-Anwendung eine explizite URL bereitstellt.

Sprachregeln und Katalog definieren #

Installiere die Pakete:

sh
npm install @lingo.dev/react@1.17.1 @lingo.dev/react-tanstack@1.17.1 @lingo.dev/locale-router@0.2.1
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npm install --save-dev @lingo.dev/cli@latest

Füge die Funktion loadMatchedMessages aus Kataloge laden als src/catalog.ts hinzu. Erstelle anschließend src/i18n.ts:

ts
import { createLocaleRouter } from "@lingo.dev/locale-router";
import type { Catalog } from "@lingo.dev/react-tanstack";
import source from "../locales/en.jsonc?raw";
import { loadMatchedMessages } from "./catalog";

export const locales = createLocaleRouter(["en", "de"] as const, {
  defaultLocale: "en",
  exclude: ["api", "assets"],
});

const targets = import.meta.glob<string>("../locales/*.jsonc", {
  query: "?raw",
  import: "default",
});

export const catalog: Catalog = async (locale) => {
  const load = targets[`../locales/${locale}.jsonc`];
  if (!load) throw new Error(`Missing catalog for ${locale}`);
  return loadMatchedMessages(source, await load());
};

Dieser Vite-Loader validiert die Rohdateien und wählt die aktiven Schlüssel aus der passenden englischen Quelle aus. So reaktivieren übersetzte Ausgaben ohne Kommentare keine verwaisten Einträge. Bei fehlenden oder fehlerhaften Dateien schlägt er fehl, statt stillschweigend eine leere Map bereitzustellen. Der nachfolgende Extraktionsschritt erstellt die importierte Quelldatei vor dem Start der Anwendung.

Anfrage vor dem Erstellen des Routers auflösen #

Registriere die Middleware für Pfade ohne Präfix in src/start.ts und behalte vorhandene Middleware bei:

ts
import { createStart } from "@tanstack/react-start";
import { localeMiddleware } from "@lingo.dev/react-tanstack/server";
import { locales } from "./i18n";

export const startInstance = createStart(() => ({
  requestMiddleware: [localeMiddleware(locales)],
}));

Verwende in src/router.tsx die ermittelte Sprache und die Texte als Router-Kontext:

tsx
import { createRouter } from "@tanstack/react-router";
import { lingoContext, localeRewrite } from "@lingo.dev/react-tanstack";
import { routeTree } from "./routeTree.gen";
import { catalog, locales } from "./i18n";

export async function getRouter() {
  const state = await lingoContext(locales, catalog);
  return createRouter({
    routeTree,
    context: state,
    rewrite: localeRewrite(locales, state.locale),
  });
}

declare module "@tanstack/react-router" {
  interface Register {
    router: Awaited<ReturnType<typeof getRouter>>;
  }
}

Behalte die übrigen Router-Einstellungen der Anwendung bei. lingoContext übernimmt das erkannte URL-Präfix oder verwendet die Standardsprache. Auf dem Server liest es die Anfrage-URL, im Browser location.href; mit einem optionalen dritten Argument URL lässt sich diese Eingabe explizit angeben. Es handelt die Sprache nicht selbst über Accept-Language aus. Die Middleware übernimmt das für geeignete Anfragen mit Pfaden ohne Präfix und antwortet mit einer 302-Weiterleitung.

localeRewrite entfernt ein erkanntes Präfix für den Routenabgleich und ergänzt ausgehende geeignete Pfade um die Sprache der Anfrage. Definiere Routen weiterhin ohne Präfix und schließe API- und Asset-Pfade wie oben von der Lokalisierung aus.

Anwendungswurzel aus dem Anfragekontext rendern #

Behalte in src/routes/__root.tsx die Framework-Grundstruktur bei und binde den Provider ein:

tsx
import { createRootRouteWithContext, HeadContent, Outlet, Scripts } from "@tanstack/react-router";
import { createLingo, LingoProvider, type Messages } from "@lingo.dev/react";

type LocaleContext = { locale: "en" | "de"; messages: Messages };

export const Route = createRootRouteWithContext<LocaleContext>()({
  component: Outlet,
  shellComponent: ({ children }) => {
    const { locale, messages } = Route.useRouteContext();
    return (
      <html lang={locale} dir={createLingo(locale).direction}>
        <head>
          <HeadContent />
        </head>
        <body>
          <LingoProvider locale={locale} messages={messages}>
            {children}
          </LingoProvider>
          <Scripts />
        </body>
      </html>
    );
  },
});

Derselbe Kontext steuert jetzt Texte, Formatierung und Dokumentattribute. Behalte ihn während der Hydration bei; würdest du die Texte durch eine leere clientseitige Map ersetzen, würde sich die gerenderte Seite verändern.

Eine übersetzte Seite und Head-Metadaten hinzufügen #

Erstelle src/routes/about.tsx:

tsx
import { createFileRoute } from "@tanstack/react-router";
import { useLingo } from "@lingo.dev/react";
import { getLingo, lingoHead } from "@lingo.dev/react-tanstack";
import { locales } from "../i18n";

export const Route = createFileRoute("/about")({
  head: (options) => {
    const l = getLingo(options);
    const localized = lingoHead({
      router: locales,
      locale: options.match.context.locale,
      pathname: options.match.pathname,
      origin: "https://example.com",
    });
    return {
      meta: [{ title: l.text("About us", { context: "About page title" }) }, ...localized.meta],
      links: localized.links,
    };
  },
  component: About,
});

function About() {
  const l = useLingo();
  return <h1>{l.text("About us", { context: "About page heading" })}</h1>;
}

Ersetze den Beispiel-Origin durch den vertrauenswürdigen Origin deiner Website. Binde const l = getLingo(options) vor den extrahierten Aufrufen in head; ein verkettetes getLingo(options).text(...) entspricht nicht dem unterstützten Extraktionsmuster.

Head-Metadaten #

lingoHead gibt { meta, links } zurück: kanonische und alternative Links für jede Sprache sowie x-default und og:url/og:locale. Gib einen Pfadnamen ohne Präfix, Abfrageparameter oder Fragment an. Für das deutsche /about lautet die kanonische URL https://example.com/de/about; nach diesen Regeln lautet die englische Standardalternative /en/about.

Die Hilfsfunktion entfernt bei allen Pfaden außer dem Wurzelpfad einen abschließenden Schrägstrich. Die Open-Graph-Sprachkennung wird aus der um Standardangaben vervollständigten Kombination aus Sprache und Region abgeleitet, etwa de_DE; mit optionalen ogLocale-Überschreibungen lassen sich plattformspezifische Schreibweisen berücksichtigen. LingoHead ist der Ergebnistyp, nicht die JSX-Komponente des Next-Adapters.

Kataloge extrahieren und abrufen #

Führe npx lingo extract --src src --source-locale en aus. Initialisiere für eine neue Konfiguration locales/en.jsonc mit den Zielsprachen de, authentifiziere dich, verknüpfe eine Lokalisierungs-Engine und rufe die erste Zielsprache ab:

sh
npx lingo init --source en --targets de --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link
npx lingo push --backfill-missing --wait

Behalte bei einer bestehenden Konfiguration deren Verknüpfungen und erweiterte Einstellungen bei. Führe nach der Extraktion die regulären Aktualisierungen für bestehende Zielsprachen durch, rufe sie ab und sieh sie dir an. Füge anschließend de hinzu und vervollständige die Übersetzungen, ohne die Quellrevision zu ändern. Folge für diesen Branch Kataloge laden und dem Verfahren zum Hinzufügen einer Sprache. Starte die Anwendung erst, wenn locales/en.jsonc und das vorgesehene locales/de.jsonc vorhanden sind. Rufe /en/about und /de/about auf, sieh dir Überschrift und Titel an und kontrolliere die zugehörigen kanonischen und alternativen URLs.

Sprache mit einer vollständigen Anfrage wechseln #

tsx
import { useLocaleSwitch } from "@lingo.dev/react-tanstack";
import { locales } from "./i18n";

export function Languages() {
  const options = useLocaleSwitch(locales);
  return (
    <nav aria-label="Language">
      {options.map((option) => (
        <a key={option.locale} href={option.href} aria-current={option.current ? "page" : undefined}>
          {option.label}
        </a>
      ))}
    </nav>
  );
}

Platziere diese Komponente unter src und rendere sie innerhalb der gerouteten Anwendung. Jede Option enthält locale, eine Eigenbezeichnung label, href und current. Einfache Links lösen eine neue Anfrage aus und laden den Katalog der jeweiligen Sprache. Rein clientseitige Routenlinks können die Texte der vorherigen Anfrage beibehalten. Die Sprachauswahl erhält Abfrageparameter und Fragment und schließt x-default von den auswählbaren Sprachen aus.

Integrierte Hilfsfunktionen für Kataloge und Server #

createCatalog(import.meta.glob("../locales/*.jsonc", { query: "?raw" }), { sourceLocale: "en" }) stellt ein zwischengespeichertes Catalog für Dateien bereit, deren Metadaten direkt verwendet werden können. Seine Module müssen zu Objekten mit default-Exporten vom Typ String aufgelöst werden. Es filtert verwaiste Einträge aus diesen Dateien heraus, speichert ein Promise pro Sprache zwischen und gibt bei fehlenden Modulen, Ladefehlern oder Parsing-Fehlern {} zurück. Wenn sourceLocale gesetzt ist, überspringt es die Datei dieser Sprache im Produktivbetrieb und greift auf die Quelle zurück. Es validiert keine flachen Strukturen mit String-Werten, filtert nicht nach Route und stellt keine verlorenen Metadaten wieder her; der obige Loader mit Quellabgleich übernimmt diese Aufgaben für übersetzte JSONC-Dateien.

Der Server-Einstiegspunkt exportiert localeMiddleware und canonicalSearch. Die Middleware erhält Abfrageparameter, serialisiert sie jedoch anhand der TanStack-Standardeinstellungen neu; Server-Anfragen enthalten kein Browser-Fragment. Pfade, die bereits ein Präfix haben, ausgeschlossen sind oder für eine separate kanonische Normalisierung infrage kommen, werden an next() weitergegeben. Die genaue Funktionsweise der Präfixe und der Kanonisierung findest du unter locale-router.

Eine reine Anwendung mit TanStack Router kann URL an lingoContext übergeben und eigene Weiterleitungen implementieren; die Start-Abhängigkeit des Hauptpakets bleibt dabei bestehen. Die Middleware und die Anfragegrundstruktur dieser Anleitung sind speziell auf Start ausgelegt.