# General Translation React SDKs (gt-react, gt-next, gt-react-native): Configurer TanStack Start
URL: https://generaltranslation.com/fr/docs/react/tanstack-start/setup.mdx
---

title: Configurer TanStack Start
description: Enregistrez le middleware de requête General Translation, initialisez une application TanStack Start, résolvez le paramètre régional et hydratez le provider.

---

`gt-tanstack-start` utilise un middleware de requête global, une initialisation du routeur au niveau du module et un loader de route racine. Le middleware crée un état local à la requête pour le code serveur, tandis que le loader racine hydrate [`<GTProvider>`](/docs/react/reference/components/gt-provider) avec le paramètre régional et les traductions.

Cette page couvre la configuration spécifique à TanStack Start. Pour le parcours complet, y compris l&#39;installation et la CLI, suivez le [TanStack Start Quickstart](/docs/react/tanstack-start-quickstart).

<Callout type="warn">
  **Attention :** `gt-tanstack-start` est expérimental et peut entraîner des modifications incompatibles.
</Callout>

*Remarque : `gt-tanstack-start` est uniquement compatible ESM. Utilisez la syntaxe `import` plutôt que CommonJS `require()`.*

## Charger les traductions [#load-translations]

Créez une fonction [`loadTranslations`](/docs/react/reference/functions/load-translations) qui importe le fichier de traduction du paramètre régional. Conservez les fichiers dans `src/` pour que Vite puisse les importer.

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

Le CLI génère ces fichiers lorsque vous exécutez [`npx gt translate`](/docs/cli/reference/commands/translate).

## Enregistrer le middleware de requête [#middleware]

Créez `src/start.ts` et enregistrez [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) comme middleware de requête global. Conservez le middleware Cross-Site Request Forgery (CSRF) de TanStack Start lorsque vous définissez une instance Start personnalisée.

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

const csrfMiddleware = createCsrfMiddleware({
  filter: ({ handlerType }) => handlerType === 'serverFn',
});

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

Le middleware résout, pour chaque requête, le paramètre régional, la région et le paramètre d’internationalisation. Il conserve le paramètre régional résolu dans le cookie de paramètre régional et met l’état de la requête à la disposition des [fonctions runtime isomorphes](/docs/react/tanstack-start/using-server-functions) sur le serveur.

## Initialiser et résoudre le paramètre régional [#initialize]

[`initializeGT`](/docs/react/reference/config#initialize), [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) et [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot) sont tous importés depuis `gt-tanstack-start` :

* **[`initializeGT`](/docs/react/reference/config#initialize)** — appelez-le une seule fois au niveau du module dans `src/router.tsx`. Étendez avec votre `gt.config.json` et passez [`loadTranslations`](/docs/react/reference/functions/load-translations).
* **[`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale)** — renvoie le paramètre régional à partir de la portée active du middleware sur le serveur, et du store de conditions du navigateur initialisé côté client.
* **[`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot)** — charge les traductions d’un paramètre régional dans le format attendu par [`<GTProvider>`](/docs/react/reference/components/gt-provider), afin que le contenu s’affiche sans flash au chargement. Consultez la [référence](/docs/react/reference/functions/get-translations-snapshot).

## Activer le routage par paramètre régional [#locale-routing]

Le routage par paramètre régional est facultatif. Avant de l’activer, configurez TanStack Router pour qu’il accepte à la fois l’URL sans préfixe du paramètre régional par défaut, comme `/about`, et les URL préfixées par un paramètre régional, comme `/es/about`.

Vous pouvez ajouter un [segment `/{-$locale}` facultatif](https://tanstack.com/router/v1/docs/guide/internationalization-i18n#i18n-with-optional-path-parameters) à vos routes basées sur des fichiers ou du code, ou utiliser l[&#39;option `rewrite`](https://tanstack.com/router/v1/docs/guide/internationalization-i18n#url-localization-via-router-rewrite) de TanStack Router pour associer les URL publiques préfixées par un paramètre régional à votre arborescence de routes existante. Par exemple, le chemin de route facultatif `/{-$locale}/about` correspond à `/about`, `/es/about` et `/ja/about`.

Une fois que le routeur accepte les deux formes d’URL, définissez `localeRouting` sur `true` dans `gt.config.json` :

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

`gt-tanstack-start` ne crée ni ne restructure les routes de votre application. Cette option lui indique de résoudre le paramètre régional à partir d’un préfixe de chemin pris en charge et de mettre à jour le pathname lorsque le paramètre régional change. Le paramètre régional par défaut reste sans préfixe, comme `/about`, tandis que les autres paramètres régionaux utilisent un préfixe, comme `/es/about`.

Sur le serveur, [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) résout le paramètre régional à partir du chemin, puis du cookie de paramètre régional, de l’en-tête `Accept-Language` et de `defaultLocale`. Sur le client, les changements de paramètre régional rechargent la page au `pathname` correspondant et conservent sa chaîne de requête et son hachage.

Le chemin de base de TanStack Router est respecté via `TSS_ROUTER_BASEPATH`.

## Initialisez le routeur et configurez la route racine [#root-route]

Ajoutez les imports et l’initialiseur [`initializeGT`](/docs/react/reference/config#initialize) à votre fichier `src/router.tsx` existant :

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

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

Ensuite, résolvez le paramètre régional et chargez l’instantané dans le loader `src/routes/__root.tsx`. Transmettez `locale` et `translations` à [`<GTProvider>`](/docs/react/reference/components/gt-provider) dans le composant shell.

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

export const Route = createRootRoute({
  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>
  );
}
```

[`<GTProvider>`](/docs/react/reference/components/gt-provider) nécessite ici à la fois `locale` et `translations` — contrairement à Next.js, où le serveur les résout, ou à React Native, où le provider les charge lui-même.

[`initializeGT`](/docs/react/reference/config#initialize) doit s’exécuter avant que [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) ne traite une requête. Terminez la configuration du routeur et de cette route racine avant de lancer le serveur de développement.

## Marquer le contenu à traduire [#content]

Dans vos composants de route, encapsulez le JSX dans [`<T>`](/docs/react/reference/components/t) et traduisez les chaînes avec [`useGT`](/docs/react/reference/hooks/use-gt). Importez-les depuis `gt-react` pour que le CLI les détecte lors de l’analyse du code source.

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

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

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

  return (
    <main>
      <T>
        <h1>Welcome to my app</h1>
        <p>This content is translated automatically.</p>
      </T>
      <input aria-label={gt('Email input field')} />
    </main>
  );
}
```