Traduza uma aplicação TanStack Start

Resolva requisições com prefixo de idioma, carregue o catálogo correspondente e renderize páginas traduzidas com URLs canônicas e um seletor de idiomas.

Mantenha as rotas da aplicação, como /about, independentes do idioma, enquanto os leitores acessam /en/about ou /de/about. @lingo.dev/react-tanstack conecta essa política de URLs ao contexto da requisição e aos catálogos. A rota continua correspondendo a /about; o idioma da requisição determina as mensagens e as URLs geradas a partir dela.

Esta receita 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 opcional do tipo peer, mas o módulo raiz do pacote importa createIsomorphicFn do Start. Instale-o junto com o adaptador, mesmo que uma aplicação que use apenas o Router forneça uma URL explícita.

Defina a política de idiomas e o catálogo #

Instale os pacotes:

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

Adicione a função loadMatchedMessages de carregamento de catálogos como src/catalog.ts. Em seguida, crie 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 carregador do Vite valida os arquivos brutos e seleciona as chaves ativas da fonte correspondente em inglês, para que a saída traduzida sem comentários não reative entradas órfãs. Ele gera um erro quando há arquivos ausentes ou malformados, em vez de fornecer silenciosamente um mapa vazio. A etapa de extração abaixo cria a fonte importada antes de a aplicação iniciar.

Resolva a requisição antes de criar o roteador #

Registre o middleware de caminhos sem prefixo em src/start.ts, mantendo os middlewares existentes:

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

Em src/router.tsx, use o idioma resolvido e as mensagens como contexto do roteador:

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

Mantenha as demais configurações do roteador da aplicação. lingoContext usa o prefixo reconhecido na URL ou, na ausência dele, o idioma padrão. Ele lê a URL da requisição no servidor e location.href no navegador; um terceiro argumento opcional, URL, permite informar essa entrada explicitamente. Ele não faz a negociação de Accept-Language por conta própria. O middleware realiza essa negociação nas requisições elegíveis com caminhos sem prefixo e responde com um redirecionamento 302.

localeRewrite remove o prefixo reconhecido para fazer a correspondência de rotas e adiciona o idioma da requisição aos caminhos de saída elegíveis. Mantenha as definições de rota sem prefixo e exclua da localização os caminhos de API e de recursos estáticos, conforme mostrado acima.

Renderize a raiz a partir do contexto da requisição #

Em src/routes/__root.tsx, preserve a estrutura do framework ao fornecer o provedor:

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

O mesmo contexto passa a orientar 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 renderizada.

Adicione uma página traduzida e metadados do cabeçalho #

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

Substitua a origem de exemplo pela origem confiável do seu site. Vincule const l = getLingo(options) antes das chamadas extraídas em head; o uso de getLingo(options).text(...) encadeado não é um padrão de extração compatível.

Metadados do cabeçalho #

lingoHead retorna { meta, links }: links canônicos e alternativos para cada idioma, além de x-default e og:url/og:locale. Forneça um caminho sem prefixo, sem parâmetros de consulta e sem fragmento. Para /about em alemão, a URL canônica é https://example.com/de/about; nesta política, a URL alternativa padrão 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 é derivado da combinação maximizada de idioma e região, como de_DE; substituições opcionais em ogLocale permitem lidar com grafias específicas de cada plataforma. LingoHead é o tipo do resultado, não o componente JSX do adaptador Next.

Extraia e obtenha 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, vincule um engine de localização e obtenha o primeiro catálogo 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 uma configuração existente, preserve os vínculos e as configurações avançadas. Após a extração, conclua as atualizações habituais dos idiomas de destino existentes, obtenha e inspecione os catálogos correspondentes e, em seguida, adicione de e preencha o conteúdo anterior, mantendo fixa a revisão da fonte. Siga Carregamento de catálogos e o procedimento de adição de idiomas para esse caso. Inicie a aplicação somente depois que locales/en.jsonc e o locales/de.jsonc desejado estiverem presentes. Acesse /en/about e /de/about, inspecione o cabeçalho e o título e verifique as URLs canônicas e alternativas.

Troque de idioma com uma requisição 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>
  );
}

Coloque este componente sob src e renderize-o dentro da aplicação com roteamento. Cada opção contém locale, um endônimo label, href e current. Links de âncora simples fazem uma nova requisição e carregam o catálogo do idioma escolhido. Links de rota que operam apenas no cliente podem manter as mensagens da requisição anterior. O seletor preserva os parâmetros de consulta e o fragmento e exclui x-default dos idiomas disponíveis para seleção.

Funções auxiliares integradas para catálogos e servidor #

createCatalog(import.meta.glob("../locales/*.jsonc", { query: "?raw" }), { sourceLocale: "en" }) fornece um Catalog com cache para arquivos cujos metadados podem ser usados diretamente. Seus módulos devem ser resolvidos como objetos com exportações default do tipo string. Ele filtra as entradas órfãs presentes nesses arquivos, armazena em cache uma promessa por idioma e retorna {} em caso de módulos ausentes, erros de carregamento ou erros de análise. Com sourceLocale definido, ele ignora o arquivo desse idioma em produção e usa a fonte como alternativa. Ele não valida estruturas planas com valores do tipo string, não filtra por rota nem restaura metadados perdidos; o carregador apresentado acima, que combina os dados com a fonte, atende a essas necessidades para JSONC traduzido.

O ponto de entrada do servidor exporta localeMiddleware e canonicalSearch. O middleware preserva os parâmetros de consulta, mas os serializa novamente usando os padrões do TanStack; requisições ao servidor não contêm o fragmento do navegador. 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 ver o comportamento exato dos prefixos e da normalização canônica.

Uma aplicação que use apenas o TanStack Router pode fornecer um URL a lingoContext e implementar seus próprios redirecionamentos, mantendo a dependência do pacote raiz em relação ao Start. O middleware e a estrutura de requisição desta receita se destinam especificamente ao Start.