# General Translation React SDKs (gt-react, gt-next, gt-react-native): TanStack Start クイックスタート
URL: https://generaltranslation.com/ja/docs/react/tanstack-start-quickstart.mdx
---

title: TanStack Start クイックスタート
description: "`gt-tanstack-start` を使って TanStack Start アプリに General Translation を追加し、最初のコンテンツを翻訳します。"
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` は、TanStack Start アプリを自動で国際化対応にします。ルーターのエントリポイントで General Translation を初期化し、リクエストのロケールを判定して、ルートのローダー から [`GTProvider`](/docs/react/reference/components/gt-provider) をハイドレートします。

このクイックスタートは TanStack Start アプリ向けです。通常の React SPA には、[React クイックスタート](/docs/react/react-quickstart) を使用してください。

<Callout type="warn">
  **警告:** `gt-tanstack-start` は実験的機能であり、破壊的変更が入る可能性があります。現時点では本番環境での使用は推奨されていません。
</Callout>

## クイックスタート [#quickstart]

パッケージをインストールし、設定ファイルと翻訳ローダーを作成して、リクエストミドルウェアを追加し、ルーターを初期化し、root routeを設定し、コンテンツを翻訳対象として指定して、翻訳を生成します。

### 1. `gt-tanstack-start` をインストール

依存関係として `gt-tanstack-start` と `gt-react` を、開発依存関係として [`gt` CLI](/docs/cli/quickstart) をインストールします。[`<T>`](/docs/react/reference/components/t) コンポーネントをソース内で CLI が検出できるようにするため、`gt-react` を直接追加する必要があります。

<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` は ESM 専用です。CommonJS の `require()` ではなく、`import` 構文を使用してください。

### 2. `gt.config.json` を作成する

プロジェクトルートに `gt.config.json` ファイルを作成します。このファイルでは、ソース言語、対象ロケール、および翻訳ファイルの出力先を定義します。

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

* `defaultLocale` — アプリを記述している言語。
* `locales` — 翻訳先の言語です。[対応ロケール](/docs/platform/dashboard/reference/supported-locales)から選択してください。
* `files.gt.output` — CLI が翻訳ファイルを書き出す場所です。Vite でインポートできるよう、`src/` 配下に置いてください。`public/` 内のファイルは解決できません。

### 3. 翻訳ローダーを作成する

実行時にロケールの翻訳ファイルをインポートする `loadTranslations.ts` ファイルを作成します。

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

### 4. リクエスト ミドルウェアを追加する

`src/start.ts` を作成し、[`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) をグローバルなリクエスト ミドルウェアとして登録します。カスタムの start インスタンスを定義する場合でも、TanStack Start&#39;s 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],
}));
```

ミドルウェアは、各リクエストごとにロケール、リージョン、国際化設定を適用し、サーバー関数が正しい言語を使用できるようにします。開発サーバーを起動する前に、次の手順で初期化を完了してください。

### 5. General Translation を初期化し、root route をセットアップする

`src/router.tsx` のモジュールスコープで [`initializeGT`](/docs/react/tanstack-start/setup#initialize) を一度呼び出します。既存のルーターファイルに import と初期化処理を追加します。

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

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

次に、[`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) でロケールを判定し、`src/routes/__root.tsx` のローダー で翻訳スナップショットを読み込みます。`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>
  );
}
```

[`getLocale`](/docs/react/tanstack-start/reference/functions/get-locale) は、サーバーではリクエストスコープのロケールを読み取り、クライアントでは初期化されたブラウザーのロケールを読み取ります。[`GTProvider`](/docs/react/reference/components/gt-provider) には `locale` と `translations` の両方が必要です。

<Callout type="warn">
  **警告:** これらの翻訳ファイル (`src/_gt/[locale].json`) は、作成するまで存在しません。デフォルトロケールは引き続き表示されますが、言語切り替え機能で対象ロケールを選択すると、ファイルが作成されるまで HTTP 500 が返されます。先に [`npx gt generate`](/docs/cli/reference/commands/generate) (API キー は不要) または [`npx gt translate`](/docs/cli/reference/commands/translate) (認証情報が必要) を実行して、これらのファイルを作成してください。
</Callout>

### 6. コンテンツを翻訳対象として指定する

インプレースで翻訳するには、JSX を [`<T>`](/docs/react/reference/components/t) コンポーネントで囲みます。CLI がソースコードをスキャンする際に検出できるよう、`gt-react` から [`<T>`](/docs/react/reference/components/t) と [`useGT`](/docs/react/reference/hooks/use-gt) をインポートしてください。

```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) は翻訳関数を直接返すため、`const gt = useGT();` のように呼び出します。

### 7. 翻訳を生成する

CLI を実行して、General Translation API 経由でプロジェクトの翻訳を生成します。

```bash
npx gt translate
```

本番ビルドで常に最新の翻訳が使われるよう、このコマンドをビルドスクリプトに追加してください。

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

<Callout type="info">
  **注:** [`npx gt translate`](/docs/cli/reference/commands/translate) の実行には、環境変数 `GT_PROJECT_ID` と `GT_API_KEY` に設定した Project ID と本番用の API キーが必要です。これらを取得するには、[`npx gt auth`](/docs/cli/reference/commands/auth) を実行するか、[ダッシュボード](/docs/platform/dashboard/get-started) にアクセスしてください。
</Callout>
## Next steps

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