# General Translation React SDKs (gt-react, gt-next, gt-react-native): TanStack Start Quickstart
URL: https://generaltranslation.com/en-US/docs/react/tanstack-start-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Add General Translation to a TanStack Start app with gt-tanstack-start, and translate your first content.

`gt-tanstack-start` adds automatic internationalization to TanStack Start apps. You initialize General Translation in the router entry point, resolve the request locale, and hydrate [`GTProvider`](/docs/react/reference/components/gt-provider) from a route loader.

Use this quickstart for TanStack Start apps. For a plain React SPA use the [React Quickstart](/docs/react/react-quickstart).

<Callout type="warn">
  **Warning:** `gt-tanstack-start` is experimental and may have breaking changes. It is not yet recommended for production use.
</Callout>

## Quickstart [#quickstart]

Install the packages, create a config file and a translation loader, add request middleware, initialize the router, wire up the root route, mark content for translation, and generate translations.

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

Install `gt-tanstack-start` and `gt-react` as dependencies, and the [`gt` CLI](/docs/cli/quickstart) as a dev dependency. `gt-react` is required directly so the CLI can detect [`<T>`](/docs/react/reference/components/t) components in your 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` is ESM-only. Use `import` syntax rather than CommonJS `require()`.

*Note: This setup requires `gt-tanstack-start` 11.1.5 or later so [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) resolves from the package's main entry in client builds.*

### 2. Create `gt.config.json`

Create a `gt.config.json` file in your project root. It declares your source language, your target locales, and where translation files are written.

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

- `defaultLocale` — the language your app is written in.
- `locales` — the languages to translate into. Pick from the [supported locales](/docs/platform/dashboard/reference/supported-locales).
- `files.gt.output` — where the CLI writes translation files. Keep them under `src/` so Vite can import them; files in `public/` will not resolve.

### 3. Create a translation loader

Create a `loadTranslations.ts` file that imports a locale's translation file at runtime.

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

### 4. Add request middleware

Create `src/start.ts` and register [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) as global request middleware. Keep TanStack Start's CSRF middleware when you define a custom start instance.

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

The middleware scopes the locale, region, and internationalization setting to each request so server functions use the correct language. Complete the initialization in the next step before starting the development server.

### 5. Initialize General Translation and set up the root route

Call [`initializeGT`](/docs/react/tanstack-start/setup#initialize) once at module scope in `src/router.tsx`. Add the imports and initializer to your existing router file:

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

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

Then resolve the locale with [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) and load a translations snapshot in the `src/routes/__root.tsx` loader. Pass the `locale` and `translations` to [`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) reads the request-scoped locale on the server and the initialized browser locale on the client. [`GTProvider`](/docs/react/reference/components/gt-provider) requires both `locale` and `translations`.

<Callout type="warn">
  **Warning:** These translation files (`src/_gt/[locale].json`) do not exist until you create them. The default locale still renders, but selecting a target locale in the language switcher returns HTTP 500 until the files exist. Run [`npx gt generate`](/docs/cli/reference/commands/generate) (no API key needed) or [`npx gt translate`](/docs/cli/reference/commands/translate) (with credentials) to create them first.
</Callout>

### 6. Mark content for translation

Wrap JSX in the [`<T>`](/docs/react/reference/components/t) component to translate it in place. Import [`<T>`](/docs/react/reference/components/t) and [`useGT`](/docs/react/reference/hooks/use-gt) from `gt-react` so the CLI detects them when scanning your 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) returns the translation function directly, so call it as `const gt = useGT();`.

### 7. Generate translations

Run the CLI to translate your project through the General Translation API.

```bash
npx gt translate
```

Add the command to your build script so production builds always have up-to-date translations:

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

<Callout type="info">
  **Note:** [`npx gt translate`](/docs/cli/reference/commands/translate) needs a project ID and a production API key, set as `GT_PROJECT_ID` and `GT_API_KEY` in your environment. Run [`npx gt auth`](/docs/cli/reference/commands/auth) or visit the [Dashboard](/docs/platform/dashboard/get-started) to get them.
</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.