Traduire une application TanStack Start
Résolvez les requêtes préfixées par une langue, chargez le catalogue correspondant et affichez des pages traduites avec des URL canoniques et un sélecteur de langue.
Gardez les routes de l’application, comme /about, indépendantes de la langue, tout en permettant aux visiteurs d’accéder à /en/about ou /de/about. @lingo.dev/react-tanstack relie cette politique d’URL au contexte de la requête et aux catalogues. La route correspond toujours à /about ; la langue de la requête détermine les messages utilisés et les URL générées à partir de celle-ci.
Ce guide ajoute l’anglais et l’allemand à une application TanStack Start existante utilisant React 19, TanStack Router 1.170+ et Start 1.168+. Start est déclaré comme dépendance homologue facultative, mais le module racine du paquet importe createIsomorphicFn de Start. Installez-le avec l’adaptateur, même si une application utilisant uniquement Router fournit une URL explicite.
Définir la politique de langue et le catalogue #
Installez les paquets :
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@latestAjoutez la fonction loadMatchedMessages présentée dans Chargement des catalogues sous le nom src/catalog.ts. Créez ensuite 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());
};Ce chargeur Vite valide les fichiers bruts et sélectionne les clés actives dans la source anglaise correspondante, pour éviter que les fichiers traduits sans commentaires ne réactivent des clés orphelines. Il échoue si des fichiers sont manquants ou mal formés, plutôt que de fournir silencieusement une table vide. L’étape d’extraction ci-dessous crée la source importée avant le démarrage de l’application.
Résoudre la requête avant de créer le routeur #
Enregistrez le middleware des chemins sans préfixe dans src/start.ts, en conservant les middlewares existants :
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)],
}));Dans src/router.tsx, utilisez la langue résolue et les messages comme contexte du routeur :
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>>;
}
}Conservez les autres paramètres du routeur de l’application. lingoContext utilise le préfixe d’URL reconnu ou, à défaut, la langue par défaut. Il lit l’URL de la requête sur le serveur et location.href dans le navigateur ; un troisième argument facultatif URL permet de fournir explicitement cette donnée. Il n’effectue pas lui-même la négociation Accept-Language. Le middleware s’en charge pour les requêtes admissibles dont le chemin est sans préfixe, puis répond par une redirection 302.
localeRewrite retire le préfixe reconnu pour permettre la correspondance des routes et ajoute la langue de la requête aux chemins sortants admissibles. Gardez les définitions de routes sans préfixe et excluez les chemins des API et des ressources de la localisation, comme ci-dessus.
Afficher la racine à partir du contexte de la requête #
Dans src/routes/__root.tsx, conservez la structure du framework tout en ajoutant le fournisseur de contexte :
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>
);
},
});Le même contexte détermine désormais le texte, la mise en forme et les attributs du document. Conservez-le pendant l’hydratation ; remplacer les messages par une table vide côté client modifierait la page affichée.
Ajouter une page traduite et des métadonnées d’en-tête #
Créez 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>;
}Remplacez l’origine donnée en exemple par l’origine de confiance de votre site. Liez const l = getLingo(options) avant les appels extraits dans head ; un appel chaîné à getLingo(options).text(...) n’est pas un schéma d’extraction pris en charge.
Métadonnées d’en-tête #
lingoHead renvoie { meta, links } : les liens canoniques et alternatifs pour chaque langue, ainsi que x-default et og:url/og:locale. Fournissez un chemin sans préfixe, sans paramètres de requête ni fragment. Pour l’allemand /about, l’URL canonique est https://example.com/de/about ; selon cette politique, l’URL alternative pour l’anglais par défaut est /en/about.
La fonction utilitaire retire une barre oblique finale des chemins autres que la racine. La langue Open Graph est dérivée de la combinaison langue/région maximisée, par exemple de_DE ; les valeurs de remplacement facultatives ogLocale permettent de gérer les graphies propres à chaque plateforme. LingoHead désigne le type du résultat, et non le composant JSX de l’adaptateur Next.
Extraire et récupérer les catalogues #
Exécutez npx lingo extract --src src --source-locale en. Pour une nouvelle configuration, initialisez locales/en.jsonc avec les langues cibles de, authentifiez-vous, associez un moteur de localisation et récupérez la première langue cible :
npx lingo init --source en --targets de --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link
npx lingo push --backfill-missing --waitPour une configuration existante, conservez ses liaisons et ses paramètres avancés. Après l’extraction, effectuez les mises à jour habituelles des langues cibles existantes, récupérez-les et inspectez-les, puis ajoutez de et effectuez un remplissage rétroactif en gardant la révision source inchangée. Suivez Chargement des catalogues et la procédure d’ajout d’une langue pour ce cas de figure. Ne démarrez l’application qu’une fois locales/en.jsonc et locales/de.jsonc présents comme prévu. Accédez à /en/about et /de/about, inspectez le titre de la page et celui du document, puis vérifiez leurs URL canoniques et alternatives.
Changer de langue avec une requête complète #
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>
);
}Placez ce composant sous src et affichez-le dans l’application routée. Chaque option contient locale, un endonyme label, href et current. Les liens classiques déclenchent une nouvelle requête et chargent le catalogue de la langue choisie. Les liens de navigation fonctionnant uniquement côté client peuvent conserver les messages de la requête précédente. Le sélecteur conserve les paramètres de requête et le fragment, et exclut x-default des langues sélectionnables.
Catalogue intégré et fonctions utilitaires côté serveur #
createCatalog(import.meta.glob("../locales/*.jsonc", { query: "?raw" }), { sourceLocale: "en" }) fournit un Catalog mis en cache pour les fichiers dont les métadonnées sont directement exploitables. Ses modules doivent se résoudre en objets dont les exports default sont des chaînes de caractères. Il filtre les clés orphelines présentes dans ces fichiers, met en cache une promesse par langue et renvoie {} en cas de module manquant, d’erreur de chargement ou d’erreur d’analyse. Lorsque sourceLocale est défini, il ignore le fichier de cette langue en production et utilise la source comme solution de repli. Il ne valide pas les structures plates à valeurs textuelles, ne filtre pas par route et ne restaure pas les métadonnées perdues ; le chargeur ci-dessus, qui effectue une jointure avec la source, répond à ces besoins pour les fichiers JSONC traduits.
Le point d’entrée du serveur exporte localeMiddleware et canonicalSearch. Le middleware conserve les paramètres de requête, mais les sérialise à nouveau selon les paramètres par défaut de TanStack ; les requêtes serveur ne contiennent pas de fragment de navigateur. Les chemins déjà préfixés, exclus ou admissibles à une normalisation canonique distincte sont transmis à next(). Consultez Routage par langue pour connaître le comportement exact des préfixes et de la canonicalisation.
Une application utilisant uniquement TanStack Router peut fournir un URL à lingoContext et implémenter ses propres redirections, tout en conservant la dépendance à Start du paquet racine. Le middleware et la structure de requête de ce guide ciblent spécifiquement Start.