# General Translation React SDKs (gt-react, gt-next): TanStack Start Quickstart
URL: https://generaltranslation.com/en-US/docs/react/tanstack-start-quickstart.mdx
---

title: TanStack Start Quickstart
description: Add General Translation to a TanStack Start app with gt-tanstack-start, and translate your first content.
related:
  links:
    - /docs/react/guides/translating-jsx
    - /docs/react/guides/translating-strings
    - /docs/react/guides/managing-locales
    - /docs/react/guides/formatting-variables

---

`gt-tanstack-start` adds automatic internationalization to TanStack Start apps. You initialize General Translation in the root route, resolve the request locale, and hydrate `GTProvider` 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="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, 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>

### 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. Set up the root route

In `src/routes/__root.tsx`, call [`initializeGT`](/docs/node/reference/functions/initialize-gt) at the module level, resolve the locale with `parseLocale`, and load a translations snapshot in the route loader. Pass the `locale` and `translations` to `GTProvider`.

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

// Initialize General Translation once, at the module level
initializeGT({ ...gtConfig, loadTranslations });

export const Route = createRootRoute({
  loader: async () => {
    const locale = parseLocale();
    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>
  );
}
```

`parseLocale` reads the locale from the request cookie and headers on the server, and from the cookie in the browser. `GTProvider` requires both `locale` and `translations`.

### 5. Mark content for translation

Wrap JSX in the `<T>` component to translate it in place. Import `<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()` returns the translation function directly, so call it as `const gt = useGT();`.

### 6. 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"
  }
}
```

*Note: `npx gt 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` or visit the [Dashboard](/docs/platform/dashboard/get-started) to get them.*

## Next steps

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