# General Translation React SDKs (gt-react, gt-next, gt-react-native): TanStack Start のセットアップ
URL: https://generaltranslation.com/ja/docs/react/tanstack-start/setup.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: General Translation のリクエスト ミドルウェアを登録し、TanStack Start アプリを初期化して、ロケールを解決し、provider をハイドレートします。

`gt-tanstack-start` はグローバルなリクエスト ミドルウェア、モジュールレベルのルーター初期化、および root route loader を使用します。ミドルウェアはサーバーコード用のリクエストローカルな state を作成し、root loader はロケールと翻訳で [`<GTProvider>`](/docs/react/reference/components/gt-provider) をハイドレートします。

このページでは、TanStack Start 固有のセットアップについて説明します。インストールや CLI を含む一連の手順については、[TanStack Start Quickstart](/docs/react/tanstack-start-quickstart) を参照してください。

<Callout type="warn">
  **警告:** `gt-tanstack-start` は実験的機能であり、破壊的変更が加わる可能性があります。
</Callout>

*メモ: `gt-tanstack-start` は ESM 専用です。CommonJS の `require()` ではなく `import` 構文を使用してください。*

*メモ: このセットアップには `gt-tanstack-start` 11.1.5 以降が必要です。これにより、クライアントビルドでは [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) がパッケージのメインエントリから解決されます。*

## 翻訳を読み込む [#load-translations]

ロケールの翻訳ファイルをインポートする [`loadTranslations`](/docs/react/reference/functions/load-translations) 関数を作成します。Vite でインポートできるように、ファイルは `src/` 配下に置いてください。

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

[`npx gt translate`](/docs/cli/reference/commands/translate) を実行すると、CLI がこれらのファイルを生成します。

## リクエストミドルウェアを登録する [#middleware]

`src/start.ts` を作成し、[`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) をグローバルリクエストミドルウェアとして登録します。カスタムの start インスタンスを定義する場合は、TanStack Start の Cross-Site Request Forgery (CSRF) ミドルウェアを維持してください。

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

ミドルウェアは、リクエストごとに一度、ロケール、リージョン、および国際化設定を解決します。解決されたロケールをロケール cookie に保持し、リクエスト状態をサーバー上の[isomorphic runtime 関数](/docs/react/tanstack-start/using-server-functions)で利用できるようにします。

## ロケールを初期化して解決する [#initialize]

[`initializeGT`](/docs/react/reference/config#initialize)、[`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale)、および [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot) は、いずれも `gt-tanstack-start` からインポートします。

* **[`initializeGT`](/docs/react/reference/config#initialize)** — `src/router.tsx` のモジュールスコープで一度だけ呼び出します。`gt.config.json` をスプレッドし、[`loadTranslations`](/docs/react/reference/functions/load-translations) を渡します。
* **[`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale)** — サーバーではアクティブなミドルウェアのスコープからロケールを返し、クライアントでは初期化済みのブラウザー条件ストアから返します。
* **[`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot)** — [`<GTProvider>`](/docs/react/reference/components/gt-provider) が想定する形式でロケールの翻訳を読み込むため、コンテンツが読み込み時にちらつかずにレンダリングされます。詳しくは [リファレンス](/docs/react/reference/functions/get-translations-snapshot) を参照してください。

## ロケールルーティングを有効にする [#locale-routing]

ロケールルーティングはオプトインです。有効にする前に、TanStack Router を設定して、`/about` のようなプレフィックスなしのデフォルトロケール URL と、`/es/about` のようなロケールプレフィックス付き URL の両方に対応させます。

ファイルベースまたはコードベースのルートに[任意の `/{-$locale}` セグメント](https://tanstack.com/router/v1/docs/guide/internationalization-i18n#i18n-with-optional-path-parameters)を追加するか、TanStack Router&#39;s [`rewrite` オプション](https://tanstack.com/router/v1/docs/guide/internationalization-i18n#url-localization-via-router-rewrite)を使用して、ロケールプレフィックス付きの公開 URL を既存のルートツリーにマッピングできます。たとえば、任意のルートパス `/{-$locale}/about` は、`/about`、`/es/about`、`/ja/about` に一致します。

ルーターが両方の URL 形式を受け入れるようになったら、`gt.config.json` で `localeRouting` を `true` に設定します。

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

`gt-tanstack-start` は、アプリケーションのルートを作成または再構成しません。このオプションを指定すると、サポートされている path プレフィックスからロケールを解決し、ロケールの変更時に pathname を更新します。デフォルトロケールは、`/about` のようにプレフィックスなしのままですが、その他のロケールでは、`/es/about` のようにプレフィックスを使用します。

サーバー側では、[`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) が path、次にロケール cookie、`Accept-Language` header、`defaultLocale` の順にロケールを解決します。クライアント側では、ロケールを変更すると対応する pathname で再読み込みされ、query string と hash は保持されます。

TanStack Router の base path は `TSS_ROUTER_BASEPATH` を通じて反映されます。

## ルーターを初期化し、root routeを設定する [#root-route]

既存の `src/router.tsx` ファイルに、[`initializeGT`](/docs/react/reference/config#initialize) のインポートと初期化処理を追加します。

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

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

次に、`src/routes/__root.tsx` の loader でロケールを解決してスナップショットを読み込みます。`locale` と `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>
  );
}
```

ここでは、[`<GTProvider>`](/docs/react/reference/components/gt-provider) に `locale` と `translations` の両方を指定する必要があります。Next.js ではサーバー側でそれらが解決され、React Native では provider 自身が読み込むため、それらとは異なります。

[`initializeGT`](/docs/react/reference/config#initialize) は、[`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) がリクエストを処理する前に実行する必要があります。開発サーバーを起動する前に、ルーター と root-route のセットアップを完了してください。

## 翻訳対象のコンテンツとしてマークする [#content]

ルートコンポーネントでは、JSX を [`<T>`](/docs/react/reference/components/t) で囲み、[`useGT`](/docs/react/reference/hooks/use-gt) を使って文字列を翻訳します。CLI がソースのスキャン時に検出できるよう、これらは `gt-react` からインポートしてください。

```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.