# General Translation React SDKs (gt-react, gt-next, gt-react-native): Démarrage rapide TanStack Start
URL: https://generaltranslation.com/fr/docs/react/tanstack-start-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Ajoutez General Translation à une application TanStack Start avec gt-tanstack-start et traduisez votre premier contenu.

`gt-tanstack-start` ajoute une internationalisation automatique aux applications TanStack Start. Vous initialisez General Translation au point d’entrée du routeur, résolvez le paramètre régional de la requête et hydratez [`GTProvider`](/docs/react/reference/components/gt-provider) à partir d’un loader de route.

Utilisez ce démarrage rapide pour les applications TanStack Start. Pour une SPA React classique, utilisez le [démarrage rapide React](/docs/react/react-quickstart).

<Callout type="warn">
  **Avertissement :** `gt-tanstack-start` est expérimental et peut introduire des changements cassants. Son utilisation en production n’est pas encore recommandée.
</Callout>

Exécutez [`npx gt@latest init`](/docs/cli/reference/commands/init) depuis la racine de l’application pour automatiser le setup. L’assistant installe le runtime, crée le loader de traductions et le middleware, initialise le routeur et configure la route racine. Il ne modifie pas les fichiers qu’il ne reconnaît pas et liste les éventuelles actions manuelles à effectuer ; ce guide présente ce même setup, effectué manuellement.

## Démarrage rapide [#quickstart]

Installez les packages, créez un fichier de configuration et un loader de traduction, ajoutez un middleware de requête, initialisez le routeur, configurez la route racine, marquez le contenu à traduire et générez les traductions.

### 1. Installez `gt-tanstack-start`

Installez `gt-tanstack-start` et `gt-react` en tant que dépendances, ainsi que la [CLI `gt`](/docs/cli/quickstart) en tant que dépendance de développement. `gt-react` est requis directement afin que la CLI puisse détecter les composants [`<T>`](/docs/react/reference/components/t) dans votre code source.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt-tanstack-start gt-react && npm install gt --save-dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-tanstack-start gt-react && yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-tanstack-start gt-react && bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-tanstack-start gt-react && pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

`gt-tanstack-start` ne prend en charge qu’ESM. Utilisez la syntaxe `import` plutôt que CommonJS `require()`.

*Remarque : cette configuration nécessite `gt-tanstack-start` 11.1.5 ou une version ultérieure afin que [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) soit résolu depuis l’entrée principale du paquet dans les builds client.*

### 2. Créez `gt.config.json`

Créez un fichier `gt.config.json` à la racine de votre projet. Il définit votre langue source, vos paramètres régionaux cibles et l’emplacement des fichiers de traduction.

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

* `defaultLocale` — la langue dans laquelle votre application est rédigée.
* `locales` — les langues vers lesquelles traduire. Choisissez parmi les [langues prises en charge](/docs/platform/dashboard/reference/supported-locales).
* `files.gt.output` — l’emplacement où le CLI génère les fichiers de traduction. Placez-les dans `src/` pour que Vite puisse les importer ; les fichiers dans `public/` ne seront pas résolus.

### 3. Créer un loader de traduction

Créez un fichier `loadTranslations.ts` qui importe le fichier de traduction du paramètre régional à l’exécution.

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

### 4. Ajouter le middleware de requête

Créez `src/start.ts` et enregistrez [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) comme middleware global de requête. Conservez le middleware 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 associe le paramètre régional, la région et le paramètre d’internationalisation à chaque requête afin que les fonctions serveur utilisent la bonne langue. Terminez l’initialisation à l’étape suivante avant de démarrer le serveur de développement.

### 5. Initialisez General Translation et configurez la route racine

Appelez [`initializeGT`](/docs/react/tanstack-start/setup#initialize) une seule fois au niveau du module dans `src/router.tsx`. Ajoutez les imports et l’initialiseur à votre fichier de routeur 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 });
```

Résolvez ensuite le paramètre régional avec [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) et chargez un instantané des traductions dans le loader `src/routes/__root.tsx`. Transmettez `locale` et `translations` à [`GTProvider`](/docs/react/reference/components/gt-provider).

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

[`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) lit le paramètre régional associé à la requête côté serveur et le paramètre régional du navigateur initialisé côté client. [`GTProvider`](/docs/react/reference/components/gt-provider) nécessite à la fois `locale` et `translations`.

<Callout type="warn">
  **Avertissement :** Ces fichiers de traduction (`src/_gt/[locale].json`) n&#39;existent pas tant que vous ne les avez pas créés. Le paramètre régional par défaut s&#39;affiche toujours, mais la sélection d&#39;un paramètre régional cible dans le sélecteur de langue renvoie une erreur HTTP 500 tant que les fichiers n&#39;existent pas. Exécutez d&#39;abord [`npx gt generate`](/docs/cli/reference/commands/generate) (aucune clé API requise), [`npx gt translate`](/docs/cli/reference/commands/translate) (avec des identifiants), ou ajoutez des fichiers vides `{}` dans `src/_gt/[locale].json`, pour les créer.
</Callout>

### 6. Marquer le contenu à traduire

Encapsulez le JSX dans le composant [`<T>`](/docs/react/reference/components/t) pour le traduire sur place. Importez [`<T>`](/docs/react/reference/components/t) et [`useGT`](/docs/react/reference/hooks/use-gt) depuis `gt-react` afin que la CLI les détecte lors de l’analyse de votre 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>
  );
}
```

[`useGT()`](/docs/react/reference/hooks/use-gt) renvoie directement la fonction de traduction. Appelez-la donc ainsi : `const gt = useGT();`.

### 7. Générer les traductions

Connectez-vous avec [`gt login`](/docs/cli/reference/commands/login), définissez le [`projectId`](/docs/cli/reference/config#project-id) de votre projet existant dans `gt.config.json` ou `GT_PROJECT_ID` dans l’environnement, puis lancez la traduction :

```bash
npx gt login
GT_PROJECT_ID=your-project-id npx gt translate
```

Ajoutez la commande à votre script de build afin que les builds de production utilisent toujours des traductions à jour :

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

<Callout type="info">
  **Remarque :** pour la CI, fournissez une `GT_API_KEY` distincte à portée restreinte ainsi que le même ID de projet via les paramètres de secrets. Utilisez [`gt init`](/docs/cli/reference/commands/init) séparément si vous avez besoin d’être guidé pour sélectionner ou créer un projet. (Voir [Identifiants du CLI](/docs/cli/guides/configuring#credentials)).
</Callout>

## Next steps

- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.