# General Translation React SDKs (gt-react, gt-next, gt-react-native): React Router クイックスタート
URL: https://generaltranslation.com/ja/docs/react/react-router-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: React Router フレームワークアプリ（Shopify Hydrogen ストアフロントを含む）に General Translation を追加し、最初のコンテンツを翻訳します。

React Router のフレームワークモードでは、`gt-react` は root route を通じて動作します。`app/root.tsx` でライブラリを初期化し、ルートローダーで訪問者ごとのロケールを解決したうえで、ルートの `Layout` から [`GTProvider`](/docs/react/reference/components/gt-provider) をレンダリングします。

このクイックスタートは、`@react-router/dev` で構築されたアプリ向けです。Vite のシングルページアプリ内で React Router をライブラリとして使用している場合は、代わりに [React SPA クイックスタート](/docs/react/react-spa-quickstart) を参照してください。

アプリのルートディレクトリで [`npx gt@latest init`](/docs/cli/reference/commands/init) を実行すると、セットアップを自動化できます。ウィザードは `gt-react` をインストールし、設定ファイルと翻訳ローダーを作成したうえで、create-react-router または Hydrogen のスターターで生成された `app/root.tsx` を設定します。それ以外の root ファイルには変更を加えず、手動で必要な作業を一覧表示します。このガイドでは、同じセットアップを手動で行う手順を説明します。

*注: このセットアップには、`gt-react` 11.1.3 以降と、リクエストごとにレンダリングを行うアプリが必要です。SPA モード (`ssr: false`) 、事前レンダリング、RSC Framework Mode には対応していません。*

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

### 1. パッケージをインストールする

`gt-react` は、アプリの翻訳機能を担うライブラリです。`gt` は、翻訳を生成する CLI です。

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt-react && npm install gt --save-dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-react && yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-react && bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-react && pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

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

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

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

* `defaultLocale` — アプリの記述に使用している言語。
* `locales` — 翻訳先の言語。[サポート対象のロケール](/docs/platform/dashboard/reference/supported-locales)から選択してください。
* `files.gt.output` — CLI が翻訳ファイルを書き出す場所。Vite がサーバーとクライアントのコードと一緒にバンドルできるよう、`app/` 配下に置いてください。

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

`app/loadTranslations.ts` を作成します。このファイルは、ルートローダーからのリクエストに応じて、対象ロケールの翻訳ファイルをインポートします。

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

次に、`app/_gt/es.json` や `app/_gt/ja.json` のように、対象ロケールごとに中身が `{}` だけの空ファイルを作成します。[`gt init`](/docs/cli/reference/commands/init) を使えば、これらのファイルは自動で作成されます。翻訳ファイルがないロケールは、デフォルト言語でレンダリングされます。

### 4. root route を設定する

`app/root.tsx` のモジュールスコープで [`initializeGT`](/docs/react/reference/config#initialize) を一度だけ呼び出し、ルートローダーからロケールと翻訳のスナップショットを返したうえで、`Layout` の内容を [`GTProvider`](/docs/react/reference/components/gt-provider) でラップします。既存のルートファイルに、ハイライトされている行を追加してください。

```tsx title="app/root.tsx"
import {
  Links,
  Meta,
  Outlet,
  Scripts,
  ScrollRestoration,
  useRouteLoaderData, // [!code ++]
} from 'react-router';
import { GTProvider, getTranslationsSnapshot, initializeGT, parseLocale } from 'gt-react'; // [!code ++]

import type { Route } from './+types/root';
import gtConfig from '../gt.config.json'; // [!code ++]
import loadTranslations from './loadTranslations'; // [!code ++]
import './app.css';

initializeGT({ ...gtConfig, loadTranslations }); // [!code ++]

// [!code ++:11]
// エラーページにはローダーデータがありません。訪問者が保存したロケールが
// デフォルトロケールで上書きされないよう、エラーページでは GTProvider を使用しません。
function RootGTProvider({ children }: { children: React.ReactNode }) {
  const data = useRouteLoaderData<typeof loader>('root');
  if (!data) return <>{children}</>;
  return (
    <GTProvider locale={data.locale} translations={data.translations}>
      {children}
    </GTProvider>
  );
}

// [!code ++:4]
export async function loader({ request }: Route.LoaderArgs) {
  const locale = parseLocale(request);
  return { locale, translations: await getTranslationsSnapshot(locale) };
}

export function Layout({ children }: { children: React.ReactNode }) {
  const locale = useRouteLoaderData<typeof loader>('root')?.locale ?? gtConfig.defaultLocale; // [!code ++]
  return (
    // [!code ++]
    <html lang={locale}>
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        {/* [!code ++] */}
        <RootGTProvider>
          {children}
          <ScrollRestoration />
        {/* [!code ++] */}
        </RootGTProvider>
        <Scripts />
      </body>
    </html>
  );
}

export default function App() {
  return <Outlet />;
}
```

`parseLocale` はまずロケールのクッキーを読み取り、次に `Accept-Language` ヘッダーを確認し、どちらもない場合は `defaultLocale` にフォールバックします。ルートにすでに `loader` がある場合は、その戻り値のオブジェクトに `locale` と `translations` を追加してください。

*注: 直接アクセスによる 404 やルートローダーのエラーなど、ルートローダーのデータが存在しないエラーページは、[`GTProvider`](/docs/react/reference/components/gt-provider) なしでレンダリングされます。このページでは [`<T>`](/docs/react/reference/components/t) や [`useLocale`](/docs/react/reference/hooks/use-locale) などの翻訳コンポーネントやフックが例外を投げ、エラーページ自体がサーバーエラーになってしまいます。そのため、ルートの `ErrorBoundary` は翻訳対象にしないでください。*

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

JSX を [`<T>`](/docs/react/reference/components/t) コンポーネントでラップしてインプレースで翻訳し、`aria-label` の値などのプレーンな文字列には [`useGT`](/docs/react/reference/hooks/use-gt) を使用します。また、訪問者が言語を切り替えられるように [`<LocaleSelector>`](/docs/react/reference/components/locale-selector) を追加します。

```tsx title="app/routes/home.tsx"
import { LocaleSelector, T, useGT } from 'gt-react';

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

  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>Welcome to my app</h1>
        <p>This content is translated automatically.</p>
      </T>
      <input aria-label={gt('Email address')} />
    </main>
  );
}
```

訪問者が言語を選択すると、[`<LocaleSelector>`](/docs/react/reference/components/locale-selector) が選択された言語をロケールクッキーに保存してページを再読み込みし、ルートローダーが新しいロケールでレンダリングします。

### 6. 翻訳を生成

[`gt login`](/docs/cli/reference/commands/login) でサインインし、既存プロジェクトの [`projectId`](/docs/cli/reference/config#project-id) を `gt.config.json` で設定するか、環境変数 `GT_PROJECT_ID` を設定してから、翻訳を実行します。

```bash
npx gt login
GT_PROJECT_ID=your-project-id npx gt translate
```

サインインしただけではプロジェクトは選択されません。プロジェクトがない場合は、[Dashboard](/docs/platform/dashboard/get-started)で作成するか、[`gt init`](/docs/cli/reference/commands/init)を実行し、開発中のリアルタイム翻訳を有効にしてプロジェクトを選択または作成してください。

開発サーバーを起動し、言語を切り替えて翻訳を確認しましょう。本番環境のビルドに常に最新の翻訳が含まれるよう、既存のビルドスクリプトの先頭にこのコマンドを追加してください:

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

翻訳をバンドルせずに CDN から読み込むには、[`npx gt configure --storage cdn`](/docs/cli/reference/commands/configure) を実行します。`app/root.tsx` に必要な変更内容が表示されます。

CDN やリバースプロキシなどでドキュメントレスポンスをキャッシュする場合は、訪問者に別の言語のページが返されないよう、ロケールごとにキャッシュを分けてください。ドキュメントレスポンスに `Vary: Cookie, Accept-Language` を付与するか、共有キャッシュの対象から除外してください。

<Callout type="info">
  **注:** CI では、別途スコープを設定した `GT_API_KEY` と同じプロジェクト ID を、secret の設定で指定してください ([CLI の認証情報](/docs/cli/guides/configuring#credentials)を参照) 。
</Callout>

## Shopify Hydrogen [#hydrogen]

Hydrogen のストアフロントは React Router フレームワークのアプリなので、同じステップで設定できます。Hydrogen 独自のビルドコマンドはそのまま使い、その前に翻訳の生成処理を追加してください:

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && shopify hydrogen build --codegen"
  }
}
```

`gt-react` は、ナビゲーション、ボタン、ページの文言など、ストアフロントのコードに含まれるテキストを翻訳します。商品タイトルや商品説明などのストアコンテンツは Shopify から取得されるため、Shopify 側で翻訳してください。

## トラブルシューティング [#troubleshooting]

<Accordions>
  <Accordion title="gt init で app/root.tsx が変更されなかった">
    ウィザードが編集するのは、create-react-router または Hydrogen のスターターと同じ構成で、まだ [`initializeGT`](/docs/react/reference/config#initialize) を呼び出していないルートファイルのみです。[ステップ 4](#quickstart) に従って手動で変更してください。
  </Accordion>

  <Accordion title="gt init が変更を加える前に停止した">
    対処方法は停止した理由によって異なります。

    * **SPA モード、事前レンダリング、または RSC Framework Mode:** このセットアップでは、リクエストごとにルートローダーで各訪問者のロケールを読み取ります。そのため、これらのモードはウィザード・手動のいずれの場合もサポートされていません。
    * **`gt-react` のバージョン範囲が 11.1.3 より古いバージョンを許容している:** `gt-react` をアップグレードし、`npx gt@latest init` を再実行してください。
    * **`appDirectory` が `app` 以外である、またはウィザードが `react-router.config` を読み取れない:** アプリがリクエストごとにレンダリングされる場合は、`npx gt@latest init --no-react-setup` を実行してソース以外をすべてセットアップしてください。その後、`files.gt.output` を含め `app/` をご自身のアプリディレクトリに置き換えて、ステップ 2〜4 を実施してください。
  </Accordion>

  <Accordion title="セレクターを使用しても言語が切り替わらない">
    クッキー が有効になっていること、ロケールが `gt.config.json` に含まれていること、セレクターが `RootGTProvider` 内でレンダリングされていることを確認してください。`<html lang>` は変わるのにテキストが変わらない場合は、[`npx gt translate`](/docs/cli/reference/commands/translate) を実行して `app/_gt/[locale].json` に翻訳を生成してください。
  </Accordion>
</Accordions>

## Next steps

- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/storing-translations

## Sitemap

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