# General Translation Knowledge Base: How do I add i18n to TanStack Start?
URL: https://generaltranslation.com/en-GB/kb/add-i18n-to-tanstack-start.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: TanStack Start has no built-in i18n, so you add a library that resolves the locale for each server request and loads messages before render. Use Paraglide JS, the library TanStack's i18n guide recommends, which General Translation maintains, and have General Translation's CLI translate its message files. General Translation's experimental gt-tanstack-start keeps copy inline in JSX instead.
Category: Internationalisation
Last updated: 2026-11-16
Authors: General Translation Team
Published: 2026-10-28

TanStack Start doesn&#39;t include an i18n layer, so you add three pieces yourself: a library that renders text in the active language, a way to resolve that language on every server request, and the translations. Start renders the full document on the server and then hydrates it in the browser, so both sides need the same locale and the same messages, or the first paint comes out in the wrong language or fails to hydrate.

## Video

The video is narrated in English, with English captions.

[How do I add i18n to TanStack Start?](https://caxecubb9c64cezv.public.blob.vercel-storage.com/films/v2/kb-add-i18n-to-tanstack-start.mp4) (48 secs)

TanStack Start has no built-in i18n, so you add a library that resolves the locale for each server request, usually from a URL prefix or cookie, and loads messages before render. General Translation's experimental gt-tanstack-start also generates the translations from copy written inline in JSX: register gtMiddleware in src/start.ts, wrap copy in <T>, and run npx gt translate.

## What TanStack Start gives you, and what it leaves

TanStack Start is &quot;a full-stack React framework powered by TanStack Router&quot;, with full-document server-side rendering (SSR), streaming, server functions, and request middleware ([TanStack Start overview](https://tanstack.com/start/latest/docs/framework/react/overview)). Several of those pieces are what an i18n set-up hangs on:

* **Locale URLs.** An optional path parameter such as `/{-$locale}/about` matches `/about`, `/es/about`, and `/fr/about` with one route file, and the router&#39;s `rewrite` option can add and strip a locale prefix instead ([TanStack Router i18n guide](https://tanstack.com/router/latest/docs/guide/internationalization-i18n)).
* **Request middleware.** Middleware registered with `createStart` in `src/start.ts` runs before every request, including SSR and server functions ([TanStack Start middleware](https://tanstack.com/start/latest/docs/framework/react/guide/middleware)). That&#39;s where an i18n library reads the URL, a cookie, or the `Accept-Language` header.
* **Loaders and `head`.** A root route loader can load the locale&#39;s messages before render, and each route&#39;s `head` sets the translated `<title>` and meta tags.

What Start leaves to you: message catalogues and the runtime that looks them up, locale detection and the cookie that remembers a choice, the `<html lang>` attribute in your root shell, plural and number formatting, `hreflang` links, and the translations themselves. TanStack&#39;s i18n guide documents Paraglide JS in depth, including a TanStack Start SSR set-up, and links community guides for Intlayer and use-intl. The TanStack CLI also has a `paraglide` add-on for new apps.

## Your options

| Library                                                                                   | How you write copy                                                                                                     | Locale on the server                                                                                                                                              | Where translations come from                                                                                                                                         |
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Paraglide JS](https://paraglidejs.com/tanstack-start), maintained by General Translation | Messages in JSON files per locale, compiled to typed functions such as `m.greeting()`                                  | `paraglideMiddleware` wraps the server handler; strategies include URL, cookie, and preferred language                                                            | General Translation&#39;s CLI translates the message files ([Paraglide integration](/docs/integrations/paraglide/quickstart)), or you and your translators fill them |
| [react-i18next](https://react.i18next.com/latest/ssr)                                     | Keys in JSON namespaces, rendered with `t('home.title')`                                                               | No TanStack Start integration in its docs; you provide a per-request instance and pass `initialLanguage` and `initialI18nStore` to the client                     | You, translators, a translation management system (TMS) such as Locize, or General Translation&#39;s CLI                                                             |
| [Lingui](https://lingui.dev/ref/vite-plugin)                                              | `<Trans>` macros inline, extracted to PO catalogues                                                                    | Its Vite plugin compiles catalogues; you activate the request&#39;s locale on the server and in the browser                                                       | You, translators, a service synced to the catalogues, or General Translation&#39;s CLI                                                                               |
| General Translation (`gt-tanstack-start`, experimental)                                   | JSX wrapped in [`<T>`](/docs/react/reference/components/t), strings with [`useGT`](/docs/react/reference/hooks/use-gt) | [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware): URL prefix (opt-in), then cookie, then `Accept-Language`, then the default locale | Generated by [`npx gt translate`](/docs/cli/reference/commands/translate) and reviewed in the Dashboard                                                              |

Use Paraglide JS when you want the set-up TanStack&#39;s i18n guide recommends, typed message functions, and per-message tree-shaking. General Translation&#39;s CLI then translates its message files. (See [How do I translate Paraglide JS messages?](/kb/general-translation-vs-paraglide)) Use react-i18next when you&#39;re bringing i18next catalogues from another app. Use Lingui when your translators work in PO files. Use `gt-tanstack-start` when you want copy to stay inline in your components, with translations generated and kept current from it.

`gt-tanstack-start` is experimental: General Translation&#39;s docs say it may have breaking changes and isn&#39;t yet recommended for production. For production today, use Paraglide JS with General Translation&#39;s CLI, or see [How do I translate a React app?](/kb/translate-react-app) for a stable React set-up.

## Add Paraglide JS to TanStack Start

TanStack maintains an official [TanStack Start example with Paraglide](https://github.com/TanStack/router/tree/main/examples/react/start-i18n-paraglide), and Paraglide&#39;s [TanStack Start guide](https://paraglidejs.com/tanstack-start) follows the same set-up. New apps can also start from the TanStack CLI&#39;s `paraglide` add-on.

1. Initialise Paraglide, which sets up `project.inlang/settings.json` and your message files:

   ```bash
   npx @inlang/paraglide-js@latest init
   ```

2. Add the Vite plugin next to `tanstackStart()` in `vite.config.ts`, with the locale strategies you want:

   ```ts title="vite.config.ts"
   import { paraglideVitePlugin } from '@inlang/paraglide-js';

   paraglideVitePlugin({
     project: './project.inlang',
     outdir: './src/paraglide',
     strategy: ['url', 'cookie', 'preferredLanguage', 'baseLocale'],
   });
   ```

3. Wrap the server handler with `paraglideMiddleware` in `src/server.ts`, so each request runs with its locale:

   ```ts title="src/server.ts"
   import { paraglideMiddleware } from './paraglide/server.js';
   import handler from '@tanstack/react-start/server-entry';

   export default {
     fetch(req: Request): Promise<Response> {
       return paraglideMiddleware(req, () => handler.fetch(req));
     },
   };
   ```

4. Set the document language in `__root.tsx` with `<html lang={getLocale()}>`, importing the function from Paraglide&#39;s generated `paraglide/runtime.js`.

For localised URLs such as `/de/about`, pass Paraglide&#39;s `localizeUrl` and `deLocalizeUrl` to the router&#39;s `rewrite` option, as the example shows.

### Translate the messages with General Translation

Keep Paraglide and add General Translation&#39;s CLI. Run [`npx gt init --no-react-setup`](/docs/cli/reference/commands/init) with your message file pattern, add the quickstart&#39;s rule for inlang message files to `gt.config.json`, and run [`npx gt translate`](/docs/cli/reference/commands/translate). The CLI writes a message file for each target locale, such as `messages/es.json`, with keys, placeholders, and variant structure unchanged, and Paraglide compiles it into the same typed functions. The [Paraglide JS quickstart](/docs/integrations/paraglide/quickstart) has the exact configuration and CI set-up.

## Add gt-tanstack-start to TanStack Start

This walkthrough uses General Translation&#39;s experimental inline library. It adds Spanish and French to a page, translates a server function, and then moves each language to its own URL. It was tested with an app scaffolded by `npx @tanstack/cli@latest create` (`@tanstack/react-start` 1.169.4), `gt-tanstack-start@11.4.16`, and `gt@2.26.11`. The package needs `@tanstack/react-start` 1.159.0 or later and is ESM-only.

The [set-up wizard](/docs/cli/reference/commands/init), `npx gt@2.26.11 init`, makes the same changes as steps 1 to 4: it installs the package and writes the loader, middleware, router call, and root route, and lists anything it can&#39;t change safely. Review its diff, or follow the steps by hand.

### 1. Install the library and CLI

```bash
npm install gt-tanstack-start@11.4.16
npm install --save-dev gt@2.26.11
```

`gt-tanstack-start` exports the shared React components, such as [`<T>`](/docs/react/reference/components/t) and [`<LocaleSelector>`](/docs/react/reference/components/locale-selector), plus server helpers. The `gt` CLI finds your source copy and writes the translation files.

### 2. Set your languages

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

Keep the output under `src/` so Vite can import the files. Then add a loader:

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

### 3. Register the request middleware

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

// Keep TanStack Start's CSRF protection for server functions.
const csrfMiddleware = createCsrfMiddleware({
  filter: ({ handlerType }) => handlerType === 'serverFn',
});

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

General Translation&#39;s [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) resolves the locale once per request, from the locale cookie, then `Accept-Language`, then `defaultLocale`, and saves it in the cookie. Each request keeps its own locale, even when several render at once.

### 4. Initialise the library and hydrate the root route

Add the initialiser to your existing `src/router.tsx`, at module scope:

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

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

// ... your existing getRouter()
```

Then load the locale and its translations in the root route, and pass both to [`<GTProvider>`](/docs/react/reference/components/gt-provider):

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

export const Route = createRootRoute({
  // Runs on the server for the first request, so the HTML is already translated.
  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&#39;s locale on the server and the cookie in the browser, so both renders agree. Setting `lang={locale}` replaces the hardcoded `lang="en"` in the starter&#39;s shell.

### 5. Mark content for translation

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

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

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

  return (
    <main>
      <T>
        <h1>Find your next project</h1>
        <p>Explore projects from teams around the world.</p>
      </T>
      <input type="search" placeholder={gt('Search projects')} aria-label={gt('Search projects')} />
    </main>
  );
}
```

[`<T>`](/docs/react/reference/components/t) translates the heading and paragraph as one unit, with the markup as context. [`useGT`](/docs/react/reference/hooks/use-gt) covers attribute strings. For names, counts, and dates inside [`<T>`](/docs/react/reference/components/t), use the [variable and formatting components](/docs/react/guides/formatting-variables).

### 6. Generate translations

Sign in with [`npx gt login`](/docs/cli/reference/commands/login), set `GT_PROJECT_ID` (or `projectId` in `gt.config.json`), and run [`npx gt translate`](/docs/cli/reference/commands/translate). It writes `src/_gt/es.json` and `src/_gt/fr.json`. Generation uses [usage-based pricing](https://generaltranslation.com/pricing).

To try the set-up without an account, run [`npx gt generate`](/docs/cli/reference/commands/generate). It writes the same files with the English source text, which you edit by hand. A locale with no file yet renders the source text and logs a warning that its translations couldn&#39;t load.

### 7. Run it and switch languages

Run `npm run dev` and pick Español in the selector. It saves the choice in the locale cookie and reloads, and the server renders Spanish. In the test app, a production build served `<html lang="es">` with the Spanish heading and placeholder for a request with `Accept-Language: es`, and `<html lang="en">` with English for a request with no preference.

### Translate in server functions and metadata

[`getGT`](/docs/react/tanstack-start/reference/functions/get-gt) translates strings inside a server function, using the request&#39;s locale:

```tsx title="src/routes/account.tsx"
import { createFileRoute } from '@tanstack/react-router';
import { createServerFn } from '@tanstack/react-start';
import { getGT } from 'gt-tanstack-start';

const loadAccount = createServerFn({ method: 'GET' }).handler(async () => {
  const gt = await getGT();
  return { title: gt('Your account') };
});

export const Route = createFileRoute('/account')({
  loader: () => loadAccount(),
  // The translated title also becomes the page's <title>.
  head: ({ loaderData }) => ({ meta: [{ title: loaderData?.title }] }),
  component: () => <h1>{Route.useLoaderData().title}</h1>,
});
```

These helpers throw on the server outside a request that [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) handled, such as at module scope. [Using server functions](/docs/react/tanstack-start/using-server-functions) covers dictionary entries and registered messages too.

### Give each language its own URL

The `gt-tanstack-start` set-up above serves every language at the same URL, chosen by the cookie or browser language. Search engines index one language per URL, so [public pages need a prefix](/kb/locale-routing-seo) such as `/es/about`. Move routes under an optional segment, such as `src/routes/{-$locale}/index.tsx` with `createFileRoute('/{-$locale}/')`, then turn on locale routing:

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

The middleware then checks the path first, and the selector navigates to the prefixed URL. In the test app, `/es` and `/es/account` rendered Spanish with `<html lang="es">`, and `/` rendered English. An unprefixed URL still follows the cookie for a returning visitor, and you add [`hreflang` links](/kb/what-is-hreflang) in each route&#39;s `head` yourself. (See the [locale routing set-up](/docs/react/tanstack-start/setup#locale-routing).)

### Ship and keep translations current

Translate before each build so new copy ships in every language:

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

[`gt validate`](/docs/cli/reference/commands/validate) fails the build on content that would break translation, before any API call. In CI, set `GT_PROJECT_ID` and a project API key as `GT_API_KEY` with **Files &gt; Write**, **Translation queue &gt; Enabled**, and **Context &gt; Write** ([CLI credentials](/docs/cli/guides/configuring#credentials)). Later runs translate only new or changed source.

Reviewers can edit any string in General Translation&#39;s [Translation Editor](/docs/platform/dashboard/guides/reviewing-translations), and [`npx gt save-local`](/docs/cli/reference/commands/save-local) sends edits made in the JSON files back so later runs keep them. A [Context Group](/docs/platform/dashboard/guides/defining-context-for-translations) holds your Glossary and Custom Prompts, so product names and tone match across this app, your docs, and your other projects. [Locadex](/docs/platform/locadex/guides/configuring-automations), General Translation&#39;s AI agent, supports TanStack Start apps and can translate new copy through pull requests.

## Common questions

### Does TanStack Start have built-in i18n?

No. TanStack Router gives you optional locale segments and URL rewrites, and Start gives you middleware and loaders, but messages, locale detection, and translations come from a library.

### Can I use react-i18next with TanStack Start?

Yes, as a React library. TanStack doesn&#39;t document it, and react-i18next&#39;s SSR guide names Next.js, Remix, and Gatsby integrations, so you wire the per-request instance and client hydration yourself.

### Is gt-tanstack-start ready for production?

Not yet: General Translation marks it experimental. Pin the version, and review the changelog before upgrading.

## Key takeaways

* TanStack Start has no i18n layer; its optional `/{-$locale}` segments, `createStart` middleware, and root loaders are where you attach one.
* Resolve the locale per request on the server and hydrate the client with the same messages, and set `<html lang>` from the loader instead of the starter&#39;s hardcoded `lang="en"`.
* Paraglide JS, the library TanStack&#39;s i18n guide recommends, is maintained by General Translation. General Translation&#39;s CLI translates its message files, and it also translates i18next JSON and Lingui&#39;s PO catalogues.
* General Translation&#39;s experimental `gt-tanstack-start` adds [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware), [`initializeGT`](/docs/react/reference/config#initialize), and [`<GTProvider>`](/docs/react/reference/components/gt-provider), keeps copy inline in [`<T>`](/docs/react/reference/components/t), and [`npx gt translate`](/docs/cli/reference/commands/translate) writes `src/_gt/[locale].json`.
* Add `"localeRouting": true` with an optional `{-$locale}` segment when each language needs its own indexable URL.

## Related questions

- [How do I add i18n to a Next.js App Router app?](https://generaltranslation.com/en-GB/kb/add-i18n-to-nextjs.mdx): Start with gt init to configure General Translation in a supported App Router project, then mark source content, generate translations and verify language switching. gt-next keeps copy in JSX with translation context; the CLI, Dashboard editor and Locadex handle generation, review and ongoing updates. This guide also shows the explicit local-file set-up.
- [How do I translate Paraglide JS messages?](https://generaltranslation.com/en-GB/kb/general-translation-vs-paraglide.mdx): Keep Paraglide JS, which General Translation now maintains, and use General Translation's CLI to translate its message files. Each run writes a file for each target locale with keys, placeholders, and variant structure intact, applies your Glossary and Custom Prompts, and translates new and changed messages before your build. Your components and Paraglide set-up stay unchanged.
- [What's the best i18n library for a React app?](https://generaltranslation.com/en-GB/kb/best-react-i18n-library.mdx): The four main React i18n libraries are General Translation's gt-react, react-i18next, Lingui and React Intl. All four render and format translations, but only gt-react also generates them, from copy written inline in your JSX. Choose react-i18next to keep i18next catalogues and plugins, Lingui for extraction to compiled catalogues, and React Intl for FormatJS and ICU MessageFormat.
- [Language redirects and SEO: URL, cookie, or Accept-Language?](https://generaltranslation.com/en-GB/kb/locale-routing-seo.mdx): Let the URL decide the language of every page you want indexed, because Googlebot sends no Accept-Language header and crawls mostly from US addresses. Use a saved cookie choice, then Accept-Language, only to pick where a neutral root such as / redirects, with a temporary 302 or 307.
- [How do I translate a React app?](https://generaltranslation.com/en-GB/kb/translate-react-app.mdx): Translating a React app means internationalising its components so they render in the user's language, then translating every string into each language you support. General Translation's gt-react translates JSX in place in the `<T>` component, and npx gt translate writes one file per language.

## Previous and next questions

- Previous question: [How do I add i18n to a Next.js Pages Router app?](https://generaltranslation.com/en-GB/kb/add-i18n-to-nextjs-pages-router.mdx)
- Next question: [How do I create a sitemap for a multilingual website?](https://generaltranslation.com/en-GB/kb/multilingual-sitemap.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/en-GB/kb/sitemap.md) for every article.
