Traducir una aplicación de TanStack Start

Resuelve solicitudes con prefijo de idioma, carga el catálogo correspondiente y renderiza páginas traducidas con URL canónicas y un selector de idioma.

Mantén las rutas de la aplicación, como /about, independientes del idioma, mientras los usuarios acceden a /en/about o /de/about. @lingo.dev/react-tanstack conecta esa política de URL con el contexto de la solicitud y los catálogos. La ruta sigue coincidiendo con /about; el idioma de la solicitud determina sus mensajes y las URL que se generan a partir de ella.

Esta guía añade inglés y alemán a una aplicación de TanStack Start existente con React 19, TanStack Router 1.170+ y Start 1.168+. Start se declara como una dependencia de pares opcional, pero el módulo raíz del paquete importa createIsomorphicFn de Start. Instálalo junto con el adaptador, incluso si una aplicación que solo utiliza Router proporciona una URL explícita.

Define la política de idiomas y el catálogo #

Instala los paquetes:

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

Añade la función loadMatchedMessages de carga de catálogos como src/catalog.ts. Después, crea 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());
};

Este cargador de Vite valida los archivos sin procesar y selecciona las claves activas de la fuente en inglés correspondiente, para que la salida traducida sin comentarios no reactive entradas huérfanas. Si faltan archivos o su formato es incorrecto, genera un error en lugar de servir un mapa vacío sin avisar. El paso de extracción que se describe a continuación crea la fuente importada antes de que se inicie la aplicación.

Resuelve la solicitud antes de crear el enrutador #

Registra el middleware para rutas sin prefijo en src/start.ts, conservando cualquier middleware existente:

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

En src/router.tsx, usa el idioma resuelto y los mensajes como contexto del enrutador:

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

Conserva los demás ajustes del enrutador de la aplicación. lingoContext toma el prefijo reconocido de la URL o utiliza el idioma predeterminado. Lee la URL de la solicitud en el servidor y location.href en el navegador; un tercer argumento opcional, URL, permite indicar esa entrada de forma explícita. No negocia Accept-Language por sí mismo. El middleware realiza esa negociación para las solicitudes a rutas sin prefijo que cumplen los criterios y responde con una redirección 302.

localeRewrite elimina el prefijo reconocido para determinar la ruta coincidente y añade el idioma de la solicitud a las rutas de salida que cumplen los criterios. Mantén las definiciones de rutas sin prefijo y excluye de la localización las rutas de API y recursos, como se muestra arriba.

Renderiza la raíz a partir del contexto de la solicitud #

En src/routes/__root.tsx, conserva la estructura del framework al incorporar el proveedor:

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

El mismo contexto determina ahora el texto, el formato y los atributos del documento. Consérvalo durante la hidratación; sustituir los mensajes por un mapa vacío en el cliente cambiaría la página renderizada.

Añade una página traducida y metadatos de cabecera #

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

Sustituye el origen de ejemplo por el origen de confianza de tu sitio. Vincula const l = getLingo(options) antes de las llamadas extraídas en head; encadenar getLingo(options).text(...) no es un patrón de extracción compatible.

Metadatos de cabecera #

lingoHead devuelve { meta, links }: enlaces canónicos y alternativos para cada idioma, además de x-default y og:url/og:locale. Proporciona una ruta sin prefijo, sin parámetros de consulta ni fragmento. Para /about en alemán, la URL canónica es https://example.com/de/about; según esta política, la URL alternativa para el inglés, el idioma predeterminado, es /en/about.

La función auxiliar elimina una barra final de las rutas que no sean la raíz. El idioma de Open Graph se deriva de la combinación maximizada de idioma y región, como de_DE; las sobrescrituras opcionales de ogLocale permiten gestionar las formas específicas de cada plataforma. LingoHead es el tipo del resultado, no el componente JSX del adaptador de Next.

Extrae y recupera los catálogos #

Ejecuta npx lingo extract --src src --source-locale en. Para una configuración nueva, inicializa locales/en.jsonc con los idiomas de destino de, autentícate, vincula un motor de localización y recupera el primer idioma de destino:

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

Para una configuración existente, conserva sus vinculaciones y ajustes avanzados. Tras la extracción, completa las actualizaciones habituales de los idiomas de destino existentes, recupéralos y revísalos; después, añade de y completa el contenido pendiente sin cambiar la revisión de la fuente. Sigue Carga de catálogos y el procedimiento para añadir idiomas para ese caso. Inicia la aplicación solo cuando estén presentes locales/en.jsonc y el locales/de.jsonc previsto. Visita /en/about y /de/about, revisa el encabezado y el título, y comprueba sus URL canónicas y alternativas.

Cambia de idioma con una solicitud completa #

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

Coloca este componente bajo src y renderízalo dentro de la aplicación enrutada. Cada opción contiene locale, un endónimo label, href y current. Los enlaces normales realizan una nueva solicitud y cargan el catálogo de ese idioma. Los enlaces de ruta que funcionan solo en el cliente pueden conservar los mensajes de la solicitud anterior. El selector conserva los parámetros de consulta y el fragmento, y excluye x-default de los idiomas seleccionables.

Catálogo y funciones auxiliares de servidor integrados #

createCatalog(import.meta.glob("../locales/*.jsonc", { query: "?raw" }), { sourceLocale: "en" }) proporciona un Catalog en caché para archivos cuyos metadatos pueden utilizarse directamente. Sus módulos deben resolverse en objetos con exportaciones default de tipo cadena. Filtra las entradas huérfanas presentes en esos archivos, almacena en caché una promesa por idioma y devuelve {} si faltan módulos o se producen errores de carga o de análisis. Si se establece sourceLocale, omite el archivo de ese idioma en producción y utiliza la fuente como alternativa. No valida estructuras planas con valores de tipo cadena, no filtra por ruta ni restaura metadatos perdidos; el cargador descrito arriba, que combina los datos con la fuente, cubre esas necesidades para los archivos JSONC traducidos.

El punto de entrada del servidor exporta localeMiddleware y canonicalSearch. El middleware conserva los parámetros de consulta, pero los vuelve a serializar con los valores predeterminados de TanStack; las solicitudes al servidor no contienen el fragmento del navegador. Las rutas que ya tienen prefijo, las excluidas o las que cumplen los criterios para una normalización canónica independiente pasan a next(). Consulta locale-router para conocer el comportamiento exacto de los prefijos y la normalización canónica.

Una aplicación que solo utiliza TanStack Router puede proporcionar un URL a lingoContext e implementar sus propias redirecciones, manteniendo la dependencia de Start del paquete raíz. El middleware y la estructura de solicitudes de esta guía están diseñados específicamente para Start.