Traduce una aplicación de TanStack Start
Resuelve solicitudes con prefijo de idioma, carga el catálogo correspondiente y renderiza páginas traducidas con URLs canónicas y un selector de idioma.
Mantén las rutas de la aplicación, como /about, independientes del idioma, mientras las personas acceden a /en/about o /de/about. @lingo.dev/react-tanstack conecta esa política de URLs 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 URLs que se generan a partir de ella.
Esta guía agrega inglés y alemán a una aplicación existente de TanStack Start con React 19, TanStack Router 1.170+ y Start 1.168+. Start se declara como una dependencia par 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 usa Router proporciona una URL explícita.
Define la política de idiomas y el catálogo #
Instala los paquetes:
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@latestAgrega la función loadMatchedMessages de carga de catálogos como src/catalog.ts. Luego crea src/i18n.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 las claves huérfanas. Si faltan archivos o tienen un formato incorrecto, genera un error en lugar de servir un mapa vacío sin avisar. El paso de extracción que se muestra más adelante 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 y conserva cualquier middleware existente:
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:
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 las demás opciones de configuración del enrutador de la aplicación. lingoContext toma el prefijo reconocido de la URL o usa el idioma predeterminado. Lee la URL de la solicitud en el servidor y location.href en el navegador; un tercer argumento opcional, URL, permite proporcionar 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 un prefijo reconocido para encontrar la ruta correspondiente y agrega el idioma de la solicitud a las rutas de salida que cumplen los criterios. Mantén las definiciones de rutas sin prefijo y excluye las rutas de API y recursos de la localización, como se mostró antes.
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:
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>
);
},
});Ahora el mismo contexto determina el texto, el formato y los atributos del documento. Consérvalo durante la hidratación; reemplazar los mensajes por un mapa vacío en el cliente cambiaría la página renderizada.
Agrega una página traducida y metadatos del encabezado #
Crea src/routes/about.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>;
}Reemplaza el origen del ejemplo por el origen de confianza de tu sitio. Vincula const l = getLingo(options) antes de las llamadas extraídas en head; un getLingo(options).text(...) encadenado no es un patrón de extracción compatible.
Metadatos del encabezado #
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 alternativa predeterminada en inglés es /en/about.
La función auxiliar elimina una barra final de las rutas que no son la raíz. El idioma de Open Graph se deriva del idioma y la región maximizados, como de_DE; las opciones de sobrescritura opcionales ogLocale permiten usar las grafías específicas de cada plataforma. LingoHead es el tipo de 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:
npx lingo init --source en --targets de --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link
npx lingo push --backfill-missing --waitSi ya tienes una configuración, conserva sus vinculaciones y opciones avanzadas. Después de la extracción, completa las actualizaciones habituales de los idiomas de destino existentes, recupéralos y revísalos; luego agrega de y completa el contenido faltante sin cambiar la revisión de la fuente. Para ese caso, sigue Carga de catálogos y el procedimiento para agregar idiomas. 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 verifica sus URLs canónicas y alternativas.
Cambia de idioma con una solicitud completa #
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 dentro de src y renderízalo en la aplicación enrutada. Cada opción contiene locale, un endónimo label, href y current. Los enlaces simples realizan una nueva solicitud y cargan el catálogo de ese idioma. Los enlaces de ruta que solo operan 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.
Funciones auxiliares integradas para catálogos y servidor #
createCatalog(import.meta.glob("../locales/*.jsonc", { query: "?raw" }), { sourceLocale: "en" }) proporciona un Catalog almacenado en caché para archivos cuyos metadatos se pueden usar directamente. Sus módulos deben resolverse en objetos con exportaciones default de tipo cadena. Filtra las claves 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 configura sourceLocale, omite el archivo de ese idioma en producción y usa la fuente como respaldo. No valida estructuras planas con valores de tipo cadena, no filtra por ruta ni restaura metadatos perdidos; el cargador anterior, 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 vuelve a serializarlos con los valores predeterminados de TanStack; las solicitudes del servidor no tienen el fragmento del navegador. Las rutas que ya tienen prefijo, están excluidas o 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 usa 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.