Traduzir uma aplicação TanStack Start
Resolva pedidos com prefixo de idioma, carregue o catálogo correspondente e apresente páginas traduzidas com URLs canónicos e um seletor de idioma.
Mantenha as rotas da aplicação, como /about, independentes do idioma, enquanto os leitores acedem a /en/about ou /de/about. @lingo.dev/react-tanstack liga essa política de URLs ao contexto do pedido e aos catálogos. A rota continua a corresponder a /about; o idioma do pedido determina as mensagens e os URLs gerados a partir dessa rota.
Este guia adiciona inglês e alemão a uma aplicação TanStack Start existente com React 19, TanStack Router 1.170+ e Start 1.168+. O Start é declarado como uma dependência de pares opcional, mas o módulo raiz do pacote importa createIsomorphicFn do Start. Instale-o juntamente com o adaptador, mesmo que uma aplicação que utilize apenas o Router forneça um URL explícito.
Definir a política de idiomas e o catálogo #
Instale os pacotes:
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@latestAdicione a função loadMatchedMessages descrita em carregamento de catálogos como src/catalog.ts. Em seguida, crie 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 carregador do Vite valida os ficheiros em bruto e seleciona as chaves ativas a partir da origem correspondente em inglês, para que o resultado traduzido sem comentários não reative entradas órfãs. Se faltarem ficheiros ou estes estiverem malformados, termina com erro em vez de devolver silenciosamente um mapa vazio. O passo de extração abaixo cria o ficheiro de origem importado antes de a aplicação arrancar.
Resolver o pedido antes de criar o encaminhador #
Registe o middleware para caminhos sem prefixo em src/start.ts, mantendo qualquer 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)],
}));Em src/router.tsx, utilize o idioma resolvido e as mensagens como contexto do encaminhador:
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>>;
}
}Mantenha as restantes definições do encaminhador da aplicação. lingoContext utiliza o prefixo reconhecido no URL ou recorre ao idioma predefinido. Lê o URL do pedido no servidor e location.href no navegador; um terceiro argumento opcional, URL, permite indicar explicitamente esse valor de entrada. Não negoceia o Accept-Language por si só. O middleware efetua essa negociação nos pedidos elegíveis com caminhos sem prefixo e responde com um redirecionamento 302.
localeRewrite remove um prefixo reconhecido para fazer a correspondência de rotas e adiciona o idioma do pedido aos caminhos de saída elegíveis. Mantenha as definições de rotas sem prefixo e exclua da localização os caminhos de API e de recursos, como indicado acima.
Apresentar a raiz a partir do contexto do pedido #
Em src/routes/__root.tsx, mantenha a estrutura base da framework ao disponibilizar o fornecedor de contexto:
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>
);
},
});O mesmo contexto passa a determinar o texto, a formatação e os atributos do documento. Preserve-o durante a hidratação; substituir as mensagens por um mapa vazio no cliente alteraria a página apresentada.
Adicionar uma página traduzida e metadados do cabeçalho #
Crie 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>;
}Substitua a origem do exemplo pela origem de confiança do seu site. Associe const l = getLingo(options) antes das chamadas extraídas em head; um getLingo(options).text(...) encadeado não corresponde ao padrão de extração suportado.
Metadados do cabeçalho #
lingoHead devolve { meta, links }: ligações canónicas e alternativas para cada idioma, além de x-default e og:url/og:locale. Forneça um caminho sem prefixo, parâmetros de consulta ou fragmento. Para /about em alemão, o URL canónico é https://example.com/de/about; segundo esta política, a alternativa predefinida em inglês é /en/about.
A função auxiliar remove uma barra final dos caminhos que não sejam a raiz. O idioma do Open Graph é obtido a partir da combinação de idioma e região expandida ao máximo, como de_DE; as substituições opcionais de ogLocale permitem adaptar as grafias a cada plataforma. LingoHead é o tipo de resultado, não o componente JSX do adaptador Next.
Extrair e obter os catálogos #
Execute npx lingo extract --src src --source-locale en. Para uma nova configuração, inicialize locales/en.jsonc com os idiomas de destino de, autentique-se, associe um motor de localização e obtenha o primeiro 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 --waitSe já existir uma configuração, mantenha as respetivas associações e definições avançadas. Após a extração, conclua as atualizações habituais dos idiomas de destino existentes, obtenha-os e inspecione-os. Depois, adicione de e preencha as traduções em falta, mantendo fixa a revisão de origem. Nesse caso, siga as instruções de Carregamento de catálogos e do procedimento de adição de idiomas. Inicie a aplicação apenas quando locales/en.jsonc e o locales/de.jsonc pretendido estiverem presentes. Aceda a /en/about e /de/about, inspecione o cabeçalho e o título e verifique os respetivos URLs canónicos e alternativos.
Mudar de idioma com um pedido completo #
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>
);
}Coloque este componente sob src e apresente-o dentro da aplicação com encaminhamento por rotas. Cada opção contém locale, um endónimo label, href e current. As ligações simples fazem um novo pedido e carregam o catálogo desse idioma. As ligações de rotas exclusivamente do lado do cliente podem manter as mensagens do pedido anterior. O seletor preserva os parâmetros de consulta e o fragmento e exclui x-default dos idiomas selecionáveis.
Funções auxiliares integradas para catálogos e servidor #
createCatalog(import.meta.glob("../locales/*.jsonc", { query: "?raw" }), { sourceLocale: "en" }) disponibiliza um Catalog com cache para ficheiros cujos metadados podem ser utilizados diretamente. Os respetivos módulos têm de resultar em objetos com exportações default do tipo cadeia de caracteres. Filtra as entradas órfãs presentes nesses ficheiros, guarda em cache uma promessa por idioma e devolve {} se faltarem módulos ou ocorrerem erros de carregamento ou de análise. Com sourceLocale definido, ignora o ficheiro desse idioma em produção e recorre ao conteúdo de origem. Não valida estruturas planas com valores do tipo cadeia de caracteres, não filtra por rota nem recupera metadados perdidos; o carregador acima, que combina as traduções com a origem, responde a essas necessidades no caso de JSONC traduzido.
O ponto de entrada do servidor exporta localeMiddleware e canonicalSearch. O middleware preserva os parâmetros de consulta, mas volta a serializá-los segundo as predefinições do TanStack; os pedidos ao servidor não contêm o fragmento do navegador. Os caminhos que já têm prefixo, estão excluídos ou são elegíveis para uma normalização canónica separada seguem para next(). Consulte locale-router para conhecer o comportamento exato dos prefixos e da normalização canónica.
Uma aplicação que utilize apenas o TanStack Router pode fornecer um URL a lingoContext e implementar os seus próprios redirecionamentos, mantendo a dependência do pacote raiz em relação ao Start. O middleware e a estrutura de processamento de pedidos deste guia destinam-se especificamente ao Start.