# General Translation Knowledge Base: Comment ajouter l’i18n à TanStack Start ?
URL: https://generaltranslation.com/fr/kb/add-i18n-to-tanstack-start.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: TanStack Start ne propose pas d’i18n intégrée. Il faut donc ajouter une bibliothèque qui résout le paramètre régional à chaque requête serveur, généralement à partir d’un préfixe d’URL ou d’un cookie, et qui charge les messages avant l’affichage. Paraglide JS, react-i18next et Lingui affichent les traductions que vous leur fournissez ; le package expérimental gt-tanstack-start de General Translation les génère en plus à partir du texte intégré dans le JSX.
Category: Internationalisation
Last updated: 2026-10-28
Authors: General Translation Team
Published: 2026-10-28

TanStack Start n’inclut pas de couche d’i18n : c’est à vous d’ajouter trois éléments, à savoir une bibliothèque qui affiche le texte dans la langue active, un moyen de résoudre cette langue à chaque requête serveur, et les traductions elles-mêmes. Start génère le document complet côté serveur, puis l’hydrate dans le navigateur. Le serveur et le client doivent donc disposer du même paramètre régional et des mêmes messages ; sinon, le premier affichage s’effectue dans la mauvaise langue ou l’hydratation échoue.

## Ce que TanStack Start vous apporte, et ce qu’il vous laisse à faire

TanStack Start est « un framework React full-stack propulsé par TanStack Router », avec rendu côté serveur (SSR) du document complet, streaming, fonctions serveur et middleware de requête ([Vue d’ensemble de TanStack Start](https://tanstack.com/start/latest/docs/framework/react/overview)). Plusieurs de ces briques servent de socle à une configuration initiale i18n :

* **URL localisées.** Un paramètre de chemin facultatif tel que `/{-$locale}/about` correspond à `/about`, `/es/about` et `/fr/about` avec un seul fichier de route. L’option `rewrite` du routeur permet aussi, à la place, d’ajouter et de retirer un préfixe du paramètre régional ([guide i18n de TanStack Router](https://tanstack.com/router/latest/docs/guide/internationalization-i18n)).
* **Middleware de requête.** Le middleware enregistré avec `createStart` dans `src/start.ts` s’exécute avant chaque requête, y compris pour le SSR et les fonctions serveur ([middleware TanStack Start](https://tanstack.com/start/latest/docs/framework/react/guide/middleware)). C’est là qu’une bibliothèque d’i18n lit l’URL, un cookie ou l’en-tête `Accept-Language`.
* **Loaders et `head`.** Un loader de la route racine peut charger les messages du paramètre régional avant le rendu, et le `head` de chaque route définit le `<title>` traduit ainsi que les balises meta.

Ce que Start vous laisse à faire : les catalogues de messages et l’exécution qui s’y réfère, la détection des paramètres régionaux et le cookie qui mémorise le choix de l’utilisateur, l’attribut `<html lang>` dans votre shell racine, le formatage des pluriels et des nombres, les liens `hreflang`, et bien sûr les traductions elles-mêmes. Le guide i18n de TanStack documente Paraglide JS en détail, y compris une configuration initiale SSR pour TanStack Start, et renvoie vers des guides communautaires pour Intlayer et use-intl. Le CLI TanStack propose également un module complémentaire `paraglide` pour les nouvelles applications.

## Vos options

| Bibliothèque                                            | Rédaction des textes                                                                                                       | Paramètre régional côté serveur                                                                                                                                                                        | Provenance des traductions                                                                                  |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| [Paraglide JS](https://paraglidejs.com/tanstack-start)  | Messages dans des fichiers JSON par paramètre régional, compilés en fonctions typées comme `m.greeting()`                  | `paraglideMiddleware` encapsule le gestionnaire serveur ; les stratégies incluent l&#39;URL, le cookie et la langue préférée                                                                           | Vous, des traducteurs ou une commande de traduction automatique que vous exécutez sur les fichiers          |
| [react-i18next](https://react.i18next.com/latest/ssr)   | Clés dans des espaces de noms JSON, affichées avec `t('home.title')`                                                       | Aucune intégration TanStack Start dans sa documentation ; vous fournissez une instance per-request et transmettez `initialLanguage` et `initialI18nStore` au client                                    | Vous, des traducteurs ou un système de gestion de la traduction (TMS) comme Locize                          |
| [Lingui](https://lingui.dev/ref/vite-plugin)            | Macros `<Trans>` intégrées, extraites vers des catalogues PO                                                               | Son plugin Vite compile les catalogues ; vous activez le paramètre régional de la requête côté serveur et dans le navigateur                                                                           | Vous, des traducteurs ou un service synchronisé avec les catalogues                                         |
| General Translation (`gt-tanstack-start`, expérimental) | JSX encapsulé dans [`<T>`](/docs/react/reference/components/t), chaînes avec [`useGT`](/docs/react/reference/hooks/use-gt) | [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) : préfixe d&#39;URL (activation volontaire), puis cookie, puis `Accept-Language`, puis le paramètre régional par défaut | Générées par [`npx gt translate`](/docs/cli/reference/commands/translate) et relues dans le tableau de bord |

Optez pour Paraglide JS si vous souhaitez la configuration initiale documentée par TanStack, des fonctions de message typées et le tree-shaking par message, et que vous disposez déjà d&#39;un moyen d&#39;alimenter les fichiers JSON. Optez pour react-i18next si vous reprenez des catalogues i18next d&#39;une autre application. Optez pour Lingui si vos traducteurs travaillent sur des fichiers PO. Optez pour General Translation si vous souhaitez que les textes restent intégrés à vos composants et que les traductions soient générées et tenues à jour à partir de ces derniers. (Pour une comparaison plus détaillée, consultez [General Translation vs. Paraglide JS](/kb/general-translation-vs-paraglide).)

`gt-tanstack-start` est expérimental : selon la documentation de General Translation, il peut faire l&#39;objet de changements incompatibles et n&#39;est pas encore recommandé en production. Pour une configuration initiale React stable dès aujourd&#39;hui, consultez [Comment traduire une application React ?](/kb/translate-react-app).

## Ajouter General Translation à TanStack Start

Ce guide ajoute l&#39;espagnol et le français à une page, traduit une fonction serveur, puis attribue à chaque langue sa propre URL. Il a été testé avec une application générée par `npx @tanstack/cli@latest create` (`@tanstack/react-start` 1.169.4), `gt-tanstack-start@11.4.16` et `gt@2.26.11`. Le paquet nécessite `@tanstack/react-start` 1.159.0 ou version ultérieure, et est disponible uniquement en ESM.

L&#39;[assistant de configuration initiale](/docs/cli/reference/commands/init), `npx gt@2.26.11 init`, effectue les mêmes modifications que les étapes 1 à 4 : il installe le paquet, écrit le loader, le middleware, l&#39;appel au routeur et la route racine, puis signale tout ce qu&#39;il ne peut pas modifier sans risque. Passez en revue son diff ou suivez les étapes manuellement.

### 1. Installer la bibliothèque et la CLI

```bash
npm install gt-tanstack-start@11.4.16
npm install --save-dev gt@2.26.11
```

`gt-tanstack-start` exporte les composants React partagés, comme [`<T>`](/docs/react/reference/components/t) et [`<LocaleSelector>`](/docs/react/reference/components/locale-selector), ainsi que des utilitaires côté serveur. La CLI `gt` détecte vos textes source et génère les fichiers de traduction.

### 2. Définissez vos langues

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json"
    }
  }
}
```

Placez les fichiers générés dans `src/` afin que Vite puisse les importer. Ajoutez ensuite un loader :

```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  const translations = await import(`./_gt/${locale}.json`);
  return translations.default;
}
```

### 3. Enregistrer le middleware de requête

```ts title="src/start.ts"
import { createCsrfMiddleware, createStart } from '@tanstack/react-start';
import { gtMiddleware } from 'gt-tanstack-start';

// Conserver la protection CSRF de TanStack Start pour les fonctions serveur.
const csrfMiddleware = createCsrfMiddleware({
  filter: ({ handlerType }) => handlerType === 'serverFn',
});

export const startInstance = createStart(() => ({
  requestMiddleware: [csrfMiddleware, gtMiddleware],
}));
```

Le [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) de General Translation résout le paramètre régional une seule fois par requête, en consultant d&#39;abord le cookie du paramètre régional, puis l&#39;en-tête `Accept-Language`, et enfin `defaultLocale`, puis l&#39;enregistre dans le cookie. Chaque requête conserve son propre paramètre régional, même lorsque plusieurs sont traitées simultanément.

### 4. Initialiser la bibliothèque et hydrater la route racine

Ajoutez l&#39;initialiseur dans votre fichier `src/router.tsx` existant, au niveau du module :

```tsx title="src/router.tsx"
import { initializeGT } from 'gt-tanstack-start';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations';

initializeGT({ ...gtConfig, loadTranslations });

// ... votre getRouter() existant
```

Chargez ensuite le paramètre régional et ses traductions dans la route racine, puis transmettez-les à [`<GTProvider>`](/docs/react/reference/components/gt-provider) :

```tsx title="src/routes/__root.tsx"
import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router';
import {
  GTProvider,
  LocaleSelector,
  getLocale,
  getTranslationsSnapshot,
} from 'gt-tanstack-start';

export const Route = createRootRoute({
  // S’exécute sur le serveur lors de la première requête : le HTML est donc déjà traduit.
  loader: async () => {
    const locale = getLocale();
    return { locale, translations: await getTranslationsSnapshot(locale) };
  },
  shellComponent: RootDocument,
});

function RootDocument({ children }: { children: React.ReactNode }) {
  const { locale, translations } = Route.useLoaderData();
  return (
    <html lang={locale}>
      <head>
        <HeadContent />
      </head>
      <body>
        <GTProvider locale={locale} translations={translations}>
          <LocaleSelector />
          {children}
        </GTProvider>
        <Scripts />
      </body>
    </html>
  );
}
```

[`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) lit le paramètre régional de la requête côté serveur et le cookie côté navigateur, ce qui garantit que les deux rendus concordent. Définir `lang={locale}` remplace la valeur `lang="en"` codée en dur dans le shell du starter.

### 5. Marquer le contenu à traduire

```tsx title="src/routes/index.tsx"
import { createFileRoute } from '@tanstack/react-router';
import { T, useGT } from 'gt-tanstack-start';

export const Route = createFileRoute('/')({ component: Home });

function Home() {
  const gt = useGT();

  return (
    <main>
      <T>
        <h1>Find your next project</h1>
        <p>Explore projects from teams around the world.</p>
      </T>
      <input type="search" placeholder={gt('Search projects')} aria-label={gt('Search projects')} />
    </main>
  );
}
```

[`<T>`](/docs/react/reference/components/t) traduit le titre et le paragraphe d&#39;un seul tenant, en s&#39;appuyant sur le balisage comme contexte. [`useGT`](/docs/react/reference/hooks/use-gt) gère les chaînes d&#39;attributs. Pour les noms, les quantités et les dates à l&#39;intérieur de [`<T>`](/docs/react/reference/components/t), utilisez les [composants de variables et de formatage](/docs/react/guides/formatting-variables).

### 6. Générer des traductions

Connectez-vous avec [`npx gt login`](/docs/cli/reference/commands/login), définissez `GT_PROJECT_ID` (ou `projectId` dans `gt.config.json`), puis exécutez [`npx gt translate`](/docs/cli/reference/commands/translate). Cette commande génère `src/_gt/es.json` et `src/_gt/fr.json`. La génération est soumise à une [tarification à l&#39;usage](https://generaltranslation.com/pricing).

Pour tester la configuration initiale sans compte, exécutez [`npx gt generate`](/docs/cli/reference/commands/generate). Cette commande génère les mêmes fichiers avec le texte source en anglais, que vous modifiez ensuite manuellement. Pour un paramètre régional qui n&#39;a pas encore de fichier, le texte source est affiché et un avertissement est consigné pour signaler que ses traductions n&#39;ont pas pu être chargées.

### 7. Lancez l&#39;application et changez de langue

Exécutez `npm run dev` et sélectionnez Español dans le sélecteur. Le choix est enregistré dans le cookie de paramètre régional, la page se recharge et le serveur affiche le contenu en espagnol. Dans l&#39;application de test, une compilation de Production a renvoyé `<html lang="es">` avec le titre et l&#39;espace réservé en espagnol pour une requête contenant `Accept-Language: es`, et `<html lang="en">` avec le contenu en anglais pour une requête sans préférence de langue.

## Traduire dans les fonctions serveur et les métadonnées

[`getGT`](/docs/react/tanstack-start/reference/functions/get-gt) traduit les chaînes dans une fonction serveur, selon le paramètre régional de la requête :

```tsx title="src/routes/account.tsx"
import { createFileRoute } from '@tanstack/react-router';
import { createServerFn } from '@tanstack/react-start';
import { getGT } from 'gt-tanstack-start';

const loadAccount = createServerFn({ method: 'GET' }).handler(async () => {
  const gt = await getGT();
  return { title: gt('Your account') };
});

export const Route = createFileRoute('/account')({
  loader: () => loadAccount(),
  // Le titre traduit devient également la balise <title> de la page.
  head: ({ loaderData }) => ({ meta: [{ title: loaderData?.title }] }),
  component: () => <h1>{Route.useLoaderData().title}</h1>,
});
```

Côté serveur, ces utilitaires lèvent une erreur en dehors d&#39;une requête traitée par [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware), par exemple au niveau du module. La page [Utiliser les fonctions serveur](/docs/react/tanstack-start/using-server-functions) traite également des entrées de dictionnaire et des messages enregistrés.

## Attribuer une URL propre à chaque langue

La configuration initiale ci-dessus sert toutes les langues à la même URL, la langue étant déterminée par le cookie ou la langue du navigateur. Or, les moteurs de recherche n&#39;indexent qu&#39;une seule langue par URL : [les pages publiques ont donc besoin d&#39;un préfixe](/kb/locale-routing-seo), comme `/es/about`. Placez les routes sous un segment facultatif, par exemple `src/routes/{-$locale}/index.tsx` avec `createFileRoute('/{-$locale}/')`, puis activez le routage selon les paramètres régionaux :

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "localeRouting": true
}
```

Le middleware vérifie alors d&#39;abord le chemin, et le sélecteur redirige vers l&#39;URL préfixée. Dans l&#39;application de test, `/es` et `/es/account` s&#39;affichaient en espagnol avec `<html lang="es">`, et `/` en anglais. Une URL sans préfixe continue de suivre le cookie pour un visiteur connu, et c&#39;est à vous d&#39;ajouter les [liens `hreflang`](/kb/what-is-hreflang) dans le `head` de chaque route. (Consultez la [configuration initiale du routage selon les paramètres régionaux](/docs/react/tanstack-start/setup#locale-routing).)

## Déployer et maintenir les traductions à jour

Traduisez avant chaque compilation pour que les nouveaux textes soient disponibles dans toutes les langues dès leur mise en production :

```json title="package.json"
{
  "scripts": {
    "build": "gt validate && gt translate && vite build"
  }
}
```

[`gt validate`](/docs/cli/reference/commands/validate) fait échouer la compilation si du contenu risque de casser la traduction, avant même tout appel à l’API. En CI, définissez `GT_PROJECT_ID` ainsi qu’une clé API de projet dans `GT_API_KEY`, avec les autorisations **Fichiers &gt; Écriture** et **File d’attente de traduction &gt; Activée** ([informations d’authentification de la CLI](/docs/cli/guides/configuring#credentials)). Les exécutions suivantes ne traduisent que le contenu source nouveau ou modifié.

Les relecteurs peuvent modifier n’importe quelle chaîne de caractères dans l’[Éditeur de Traduction](/docs/platform/dashboard/guides/reviewing-translations) de General Translation, et [`npx gt save-local`](/docs/cli/reference/commands/save-local) renvoie les modifications apportées aux fichiers JSON pour que les exécutions suivantes les conservent. Un [groupe de contexte](/docs/platform/dashboard/guides/defining-context-for-translations) regroupe votre glossaire et vos instructions personnalisées, afin que les noms de produits et le ton restent cohérents entre cette application, votre documentation et vos autres projets. [Locadex](/docs/platform/locadex/guides/configuring-automations), l’agent IA de General Translation, prend en charge les applications TanStack Start et peut traduire les nouveaux textes via des pull requests.

## Questions fréquentes

### TanStack Start intègre-t-il nativement l&#39;i18n ?

Non. TanStack Router propose des segments de paramètre régional facultatifs et la réécriture d&#39;URL, et Start fournit des middleware et des loaders, mais les messages, la détection des paramètres régionaux et les traductions relèvent d&#39;une bibliothèque.

### Puis-je utiliser react-i18next avec TanStack Start ?

Oui, en tant que bibliothèque React. TanStack ne documente pas cette configuration, et le guide SSR de react-i18next ne cite que les intégrations Next.js, Remix et Gatsby : c&#39;est donc à vous de mettre en place l&#39;instance per-request et l&#39;hydratation côté client.

### gt-tanstack-start est-il prêt pour la production ?

Pas encore : General Translation le considère comme expérimental. Figez la version et consultez le changelog avant toute mise à jour.

## Points clés

* TanStack Start ne dispose d&#39;aucune couche i18n ; c&#39;est à ses segments facultatifs `/{-$locale}`, au middleware `createStart` et aux loaders racine que vous devez en greffer une.
* Résolvez le paramètre régional à chaque requête côté serveur, hydratez le client avec les mêmes messages et définissez `<html lang>` depuis le loader, au lieu de conserver le `lang="en"` codé en dur du modèle de départ.
* Paraglide JS est la bibliothèque documentée par TanStack ; Paraglide JS, react-i18next et Lingui se contentent tous d&#39;afficher les traductions que vous leur fournissez.
* Le package expérimental `gt-tanstack-start` de General Translation ajoute [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware), [`initializeGT`](/docs/react/reference/config#initialize) et [`<GTProvider>`](/docs/react/reference/components/gt-provider), et conserve le contenu intégré dans [`<T>`](/docs/react/reference/components/t) ; [`npx gt translate`](/docs/cli/reference/commands/translate) génère ensuite `src/_gt/[locale].json`.
* Ajoutez `"localeRouting": true` avec un segment facultatif `{-$locale}` lorsque chaque langue doit disposer de sa propre URL indexable.

## Related questions

- [Comment ajouter l’i18n à une application Next.js App Router ?](https://generaltranslation.com/fr/kb/add-i18n-to-nextjs.mdx): Commencez par gt init pour configurer General Translation dans un projet App Router pris en charge, puis balisez le contenu source, générez les traductions et vérifiez le changement de langue. gt-next conserve les textes dans le JSX avec leur contexte de traduction ; la CLI, l’éditeur du tableau de bord et Locadex prennent en charge la génération, la relecture et les mises à jour continues. Ce guide présente également la configuration initiale explicite avec des fichiers locaux.
- [General Translation ou Paraglide JS : lequel choisir ?](https://generaltranslation.com/fr/kb/general-translation-vs-paraglide.mdx): Choisissez General Translation pour garder vos textes intégrés au code et générer des traductions qui tiennent compte de la structure de vos composants React, d’une terminologie partagée et d’une relecture dans le tableau de bord. Choisissez Paraglide JS pour des fonctions de messages compilées et typées, avec un tree-shaking message par message. Paraglide affiche vos catalogues ; General Translation relie vos textes source à la génération des traductions et à leurs mises à jour au fil de l’eau.
- [Quelle est la meilleure bibliothèque d’i18n pour une application React ?](https://generaltranslation.com/fr/kb/best-react-i18n-library.mdx): Les quatre principales bibliothèques d’i18n pour React sont gt-react de General Translation, react-i18next, Lingui et React Intl. Toutes les quatre affichent et formatent les traductions, mais seule gt-react les génère aussi, à partir du texte intégré directement dans votre JSX. Choisissez react-i18next pour conserver vos catalogues et plugins i18next, Lingui pour l’extraction vers des catalogues compilés, et React Intl pour FormatJS et ICU MessageFormat.
- [Redirections linguistiques et SEO : URL, cookie ou Accept-Language ?](https://generaltranslation.com/fr/kb/locale-routing-seo.mdx): Laissez l’URL déterminer la langue de chaque page que vous souhaitez faire indexer, car Googlebot n’envoie aucun en-tête Accept-Language et explore principalement depuis des adresses américaines. Ne vous servez du choix enregistré dans un cookie, puis d’Accept-Language, que pour décider vers où redirige une racine neutre comme /, avec une redirection temporaire 302 ou 307.
- [Comment traduire une application React ?](https://generaltranslation.com/fr/kb/translate-react-app.mdx): Traduire une application React consiste à internationaliser ses composants pour qu’ils s’affichent dans la langue de l’utilisateur, puis à traduire chaque chaîne de caractères dans chacune des langues prises en charge. gt-react de General Translation traduit le JSX sur place dans le composant `<T>`, et npx gt translate génère un fichier par langue.

## Previous and next questions

- Previous question: [Alternatives à Weglot : General Translation vs Weglot](https://generaltranslation.com/fr/kb/general-translation-vs-weglot.mdx)
- Next question: [Comment ajouter l’i18n à une application Next.js utilisant le Pages Router ?](https://generaltranslation.com/fr/kb/add-i18n-to-nextjs-pages-router.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/fr/kb/sitemap.md) for every article.