# General Translation React SDKs (gt-react, gt-next, gt-react-native): Set up TanStack Start
URL: https://generaltranslation.com/en-US/docs/react/tanstack-start/setup.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Register General Translation request middleware, initialize a TanStack Start app, resolve the locale, and hydrate the provider.

`gt-tanstack-start` uses global request middleware, module-level router initialization, and a root route loader. The middleware creates request-local state for server code, while the root loader hydrates [`<GTProvider>`](/docs/react/reference/components/gt-provider) with the locale and translations.

This page covers the TanStack Start-specific setup. For the full path including installation and the CLI, follow the [TanStack Start Quickstart](/docs/react/tanstack-start-quickstart).

<Callout type="warn">
  **Warning:** `gt-tanstack-start` is experimental and may have breaking changes.
</Callout>

*Note: `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.*

## Load translations [#load-translations]

Create a [`loadTranslations`](/docs/react/reference/functions/load-translations) function that imports a locale's translation file. Keep the files under `src/` so Vite can import them.

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

The CLI generates these files when you run [`npx gt translate`](/docs/cli/reference/commands/translate).

## Register request middleware [#middleware]

Create `src/start.ts` and register [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) as global request middleware. Keep TanStack Start's Cross-Site Request Forgery (CSRF) middleware when defining 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 resolves the locale, region, and internationalization setting once per request. It persists the resolved locale in the locale cookie and makes request state available to the [isomorphic runtime functions](/docs/react/tanstack-start/using-server-functions) on the server.

## Initialize and resolve the locale [#initialize]

[`initializeGT`](/docs/react/reference/config#initialize), [`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale), and [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot) are all imported from `gt-tanstack-start`:

- **[`initializeGT`](/docs/react/reference/config#initialize)** — call once at module scope in `src/router.tsx`. Spread in your `gt.config.json` and pass [`loadTranslations`](/docs/react/reference/functions/load-translations).
- **[`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale)** — returns the locale from the active middleware scope on the server and from the initialized browser condition store on the client.
- **[`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot)** — loads a locale's translations in the shape [`<GTProvider>`](/docs/react/reference/components/gt-provider) expects, so content renders without a loading flash. See the [reference](/docs/react/reference/functions/get-translations-snapshot).

## Enable locale routing [#locale-routing]

Locale routing is opt-in. Before you enable it, configure TanStack Router to match both the unprefixed default-locale URL, such as `/about`, and locale-prefixed URLs, such as `/es/about`.

You can add an [optional `/{-$locale}` segment](https://tanstack.com/router/v1/docs/guide/internationalization-i18n#i18n-with-optional-path-parameters) to your file-based or code-based routes, or use TanStack Router's [`rewrite` option](https://tanstack.com/router/v1/docs/guide/internationalization-i18n#url-localization-via-router-rewrite) to map locale-prefixed public URLs to your existing route tree. For example, the optional route path `/{-$locale}/about` matches `/about`, `/es/about`, and `/ja/about`.

After the router accepts both URL shapes, set `localeRouting` to `true` in `gt.config.json`:

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

`gt-tanstack-start` does not create or restructure your application routes. The option tells it to resolve the locale from a supported path prefix and update the pathname when the locale changes. The default locale remains unprefixed, such as `/about`, while other locales use a prefix, such as `/es/about`.

On the server, [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) resolves the locale from the path, then the locale cookie, the `Accept-Language` header, and `defaultLocale`. On the client, locale changes reload at the corresponding pathname and preserve its query string and hash.

TanStack Router's base path is respected through `TSS_ROUTER_BASEPATH`.

## Initialize the router and wire up the root route [#root-route]

Add the [`initializeGT`](/docs/react/reference/config#initialize) imports and initializer to your existing `src/router.tsx` 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 and load the snapshot in the `src/routes/__root.tsx` loader. Pass `locale` and `translations` to [`<GTProvider>`](/docs/react/reference/components/gt-provider) in the shell component.

```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) requires both `locale` and `translations` here — unlike Next.js, where the server resolves them, or React Native, where the provider loads them itself.

[`initializeGT`](/docs/react/reference/config#initialize) must run before [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) handles a request. Finish the router and root-route setup before starting the development server.

## Mark content for translation [#content]

In your route components, wrap JSX in [`<T>`](/docs/react/reference/components/t) and translate strings with [`useGT`](/docs/react/reference/hooks/use-gt). Import them 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>
  );
}
```

## Sitemap

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