Přeložte aplikaci TanStack Start

Zpracujte požadavky s jazykovou předponou, načtěte odpovídající katalog a vykreslete přeložené stránky s kanonickými URL a přepínačem jazyků.

Trasy aplikace, například /about, ponechte nezávislé na jazyce, zatímco návštěvníci budou otevírat /en/about nebo /de/about. @lingo.dev/react-tanstack propojuje tato pravidla pro URL s kontextem požadavku a katalogy. Trasa se stále páruje s /about; jazyk požadavku určuje její texty i URL, které se z ní generují.

V tomto návodu přidáte angličtinu a němčinu do stávající aplikace TanStack Start s React 19, TanStack Router 1.170+ a Start 1.168+. Start je deklarován jako nepovinná závislost typu peer, kořenový modul balíčku ale importuje createIsomorphicFn ze Start. Nainstalujte jej společně s adaptérem, i když aplikace používající pouze Router předává URL explicitně.

Definujte pravidla pro jazyky a katalog #

Nainstalujte balíčky:

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

Přidejte funkci loadMatchedMessages z části Načítání katalogů jako src/catalog.ts. Poté vytvořte 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());
};

Tento loader pro Vite ověřuje nezpracované soubory a vybírá aktivní klíče z odpovídajícího anglického zdroje. Přeložený výstup bez komentářů tak znovu neaktivuje osiřelé položky. Pokud soubory chybí nebo mají nesprávný formát, loader skončí chybou, místo aby bez upozornění vrátil prázdnou mapu. Níže uvedený krok extrakce vytvoří importovaný zdroj před spuštěním aplikace.

Určete jazyk požadavku před vytvořením routeru #

V src/start.ts zaregistrujte middleware pro cesty bez jazykové předpony a zachovejte veškerý stávající middleware:

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)],
}));

V src/router.tsx použijte určený jazyk a texty jako kontext routeru:

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>>;
  }
}

Ostatní nastavení routeru aplikace ponechte beze změny. lingoContext převezme rozpoznanou předponu URL nebo použije výchozí jazyk. Na serveru čte URL požadavku a v prohlížeči location.href; nepovinný třetí argument URL umožňuje tento vstup zadat explicitně. Funkce sama jazyk podle Accept-Language nevyjednává. To zajišťuje middleware u požadavků na cesty bez předpony, které splňují příslušné podmínky, a odpovídá přesměrováním 302.

localeRewrite při párování tras odebere rozpoznanou předponu a ke generovaným cestám, které splňují příslušné podmínky, přidá jazyk požadavku. Definice tras ponechte bez předpon a cesty k API a statickým souborům vylučte z lokalizace, jak je uvedeno výše.

Vykreslete kořenovou komponentu z kontextu požadavku #

V src/routes/__root.tsx zachovejte obalovou strukturu frameworku a přidejte poskytovatele:

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>
    );
  },
});

Stejný kontext nyní řídí text, formátování i atributy dokumentu. Zachovejte jej i při hydrataci; nahrazení textů prázdnou mapou na klientovi by změnilo vykreslenou stránku.

Přidejte přeloženou stránku a metadata hlavičky #

Vytvořte 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>;
}

Nahraďte ukázkový origin důvěryhodným originem svého webu. V head nejprve přiřaďte const l = getLingo(options) a až poté použijte volání určená k extrakci; zřetězené getLingo(options).text(...) není podporovaný vzor pro extrakci.

Metadata hlavičky #

lingoHead vrací { meta, links }: kanonické a alternativní odkazy pro každý jazyk spolu s x-default a og:url/og:locale. Předejte cestu bez předpony, parametrů dotazu a fragmentu. Pro německou cestu /about je kanonická URL https://example.com/de/about; výchozí anglická alternativa je podle těchto pravidel /en/about.

Pomocná funkce odebírá jedno koncové lomítko z cest, které nevedou do kořene. Jazyk pro Open Graph se odvozuje z jazykového identifikátoru s doplněnými údaji o jazyce a oblasti, například de_DE; nepovinná přepsání ogLocale umožňují použít zápis specifický pro danou platformu. LingoHead je typ výsledku, nikoli JSX komponenta adaptéru pro Next.

Extrahujte a stáhněte katalogy #

Spusťte npx lingo extract --src src --source-locale en. U nové konfigurace inicializujte locales/en.jsonc s cílovými jazyky de, proveďte ověření, připojte lokalizační engine a stáhněte první cílový katalog:

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

U stávající konfigurace zachovejte její vazby a pokročilá nastavení. Po extrakci dokončete běžné aktualizace stávajících cílových jazyků, stáhněte je a zkontrolujte. Poté přidejte de a doplňte chybějící překlady, přičemž revizi zdroje ponechte beze změny. Pro tuto variantu postupujte podle části Načítání katalogů a postupu přidání jazyka. Aplikaci spusťte teprve tehdy, až budou k dispozici locales/en.jsonc a požadovaný locales/de.jsonc. Otevřete /en/about a /de/about, zkontrolujte nadpis a titulek stránky a ověřte jejich kanonické a alternativní URL.

Přepínejte jazyk pomocí nového požadavku #

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>
  );
}

Umístěte tuto komponentu pod src a vykreslete ji v aplikaci v rámci směrovaných tras. Každá možnost obsahuje locale, název jazyka v daném jazyce label, href a current. Běžné odkazy vyvolají nový požadavek a načtou katalog daného jazyka. Odkazy na trasy fungující pouze na klientovi mohou ponechat texty z předchozího požadavku. Přepínač zachovává parametry dotazu i fragment a v nabídce jazyků vynechává x-default.

Vestavěné pomocné funkce pro katalogy a server #

createCatalog(import.meta.glob("../locales/*.jsonc", { query: "?raw" }), { sourceLocale: "en" }) poskytuje Catalog s cache pro soubory, jejichž metadata lze použít přímo. Jeho moduly se musí načíst jako objekty s řetězcovými exporty default. Filtruje osiřelé položky v těchto souborech, ukládá do cache jeden příslib pro každý jazyk a při chybějících modulech, chybách načítání nebo parsování vrací {}. Pokud je nastaveno sourceLocale, v produkci přeskočí soubor daného jazyka a jako náhradu použije zdroj. Neověřuje plochou strukturu s řetězcovými hodnotami, nefiltruje podle trasy ani neobnovuje ztracená metadata; tyto úlohy u přeloženého JSONC zajišťuje výše uvedený loader propojující překlad se zdrojem.

Serverový vstupní modul exportuje localeMiddleware a canonicalSearch. Middleware zachovává parametry dotazu, ale znovu je serializuje podle výchozího nastavení TanStack; serverové požadavky neobsahují fragment URL z prohlížeče. Cesty, které již mají předponu, jsou z lokalizace vyloučené nebo splňují podmínky pro samostatnou kanonickou normalizaci, se předávají dál do next(). Přesná pravidla pro předpony a kanonizaci najdete v části locale-router.

Aplikace používající pouze TanStack Router může předat URL do lingoContext a implementovat vlastní přesměrování. Závislost kořenového balíčku na Start přitom zůstává zachována. Middleware a obalová struktura pro zpracování požadavku v tomto návodu jsou určeny přímo pro Start.