# General Translation React SDKs (gt-react, gt-next, gt-react-native): React SPA クイックスタート
URL: https://generaltranslation.com/ja/docs/react/react-spa-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: シングルページの React アプリケーションに複数言語対応を追加します。

このガイドを終える頃には、シングルページの React アプリでコンテンツを複数の言語で表示できるようになり、ユーザーが操作できる言語切り替え機能も備わります。

シングルページアプリでは、`gt-react` は完全にブラウザ上で動作します。起動時に [`initializeGTSPA()`](/docs/react/reference/config#initialize-spa) で一度初期化するだけでよく、provider コンポーネントは必要ありません。

**前提条件:**

* クライアントサイドでレンダリングされる React アプリ (Vite、webpack など)
* Node.js 18+

ビルドシステムによっては、より新しいバージョンの Node.js が必要になる場合があります。たとえば Vite 8 では `^20.19.0 || >=22.12.0` が必要です。

<Callout type="info">
  **ヒント:** `npx gt@latest` を実行すると、[setup wizard](/docs/cli/quickstart) を使って Vite のブートストラップと翻訳の読み込みを設定できます。このガイドでは手動でのセットアップを説明します。
</Callout>

<Callout type="info">
  **注:** アプリがサーバー側でレンダリングされる場合は、代わりに [React Quickstart](/docs/react/react-quickstart) を参照してください。
</Callout>

## バンドラーを選択する [#bundlers]

以下の手順では、主な例として Vite を使用します。ほかのビルドシステムを使用する場合は、
エントリポイント、ブートストラップ、翻訳ローダーについて、それぞれのセットアップガイドを参照してください。

<Cards>
  <Card title="Vite" href="/docs/react/guides/spa/configuring-vite-spa">
    Vite の HTML エントリと翻訳の読み込みを設定します。
  </Card>

  <Card title="webpack" href="/docs/react/guides/spa/configuring-webpack-spa">
    webpack のエントリと翻訳コンテキストを設定します。
  </Card>

  <Card title="esbuild" href="/docs/react/guides/spa/configuring-esbuild-spa">
    esbuild のエントリポイントと出力ターゲットのフォールバックを設定します。
  </Card>

  <Card title="Rollup" href="/docs/react/guides/spa/configuring-rollup-spa">
    Rollup の入力と静的に解析できるロケールマップを設定します。
  </Card>

  <Card title="Rolldown" href="/docs/react/guides/spa/configuring-rolldown-spa">
    Rolldown の入力と静的に解析できるロケールマップを設定します。
  </Card>

  <Card title="Bazel" href="/docs/react/guides/spa/configuring-bazel-spa">
    ブートストラップ、設定、package、翻訳を Bazel の入力として宣言します。
  </Card>
</Cards>

セットアップ後は、JSX、文字列、ロケールの選択、検証に関する SPA 固有のガイダンスについて、[React SPA の国際化](/docs/react/guides/spa/internationalizing-react-spa)
を参照してください。

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

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

`gt-react` は、アプリで翻訳機能を動かすライブラリです。`gt` は、翻訳の準備を行う CLI ツールです。

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-react
    npm i -D gt
    ```
  </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`** ファイルを作成します。このファイルで、サポートする言語をライブラリに指定します。

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

* **`defaultLocale`** — アプリの記述に使う言語 (翻訳元の言語) 。
* **`locales`** — 翻訳先にしたい言語です。[サポートされているロケールの一覧](/docs/platform/dashboard/reference/supported-locales) から任意に選んでください。
* **`files`** — CLI に翻訳ファイルの保存先を指定します。`output` パスは、[`loadTranslations`](/docs/react/reference/functions/load-translations) 関数内の import パス (ステップ 3) と一致している必要があります。

CLI はデフォルトで `src`、`app`、`pages`、`components` 配下の JavaScript および TypeScript ファイルをスキャンします。ソースがそれ以外の場所にある場合は [`src`](/docs/cli/reference/config#src) を設定してください。

<Callout type="info">
  **メモ:** Vite のようなバンドラーは翻訳ファイルをモジュールとして import するため、翻訳ファイルは `src/` 内に配置する必要があります。
</Callout>

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

SPA では、`gt-react` がブラウザで実行時に翻訳ファイルを読み込むための関数が必要です。[`loadTranslations`](/docs/react/reference/functions/load-translations) ファイルを作成します：

```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  try {
    const translations = await import(`./_gt/${locale}.json`);
    return translations.default;
  } catch (error) {
    console.warn(`No translations found for ${locale}`);
    return {};
  }
}
```

この関数は、`src/_gt/` ディレクトリにある JSON の翻訳ファイルを読み込みます。これらのファイルは、[`npx gt translate`](/docs/cli/reference/commands/translate) を実行すると CLI が生成します。

<Callout type="info">
  **Rollup:** 通常の Rollup では、上記の完全に動的なインポートを解析できません。代わりに[静的ロケールローダーマップ](/docs/react/guides/developing-spa-translations#setup)を使用してください。
</Callout>

<Accordions>
  <Accordion title="Create React App の翻訳を public に保持しますか？">
    Create React App では、上記のソースディレクトリローダーを使用できます。生成された翻訳を `public/` に保持する場合は、CLI の出力を `public/_gt/[locale].json` に変更します：

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

    `PUBLIC_URL` を使用して HTTP 経由でファイルを読み込みます：

    ```ts title="src/loadTranslations.ts"
    export default async function loadTranslations(locale: string) {
      try {
        const response = await fetch(
          `${process.env.PUBLIC_URL}/_gt/${locale}.json`
        );
        if (!response.ok) throw new Error('Translation file not found');
        return await response.json();
      } catch {
        console.warn(`No translations found for ${locale}`);
        return {};
      }
    }
    ```
  </Accordion>
</Accordions>

### 4. ライブラリを初期化する

アプリのレンダリング前、起動時に **[`initializeGTSPA`](/docs/react/reference/config#initialize-spa)** を一度だけ呼び出します。これは設定と翻訳ローダーを受け取り、ユーザーのロケールを判定して、そのロケールの翻訳を読み込みます。

最も堅牢なパターンは、先に GT を初期化してからアプリ本体を読み込む小さなエントリモジュールを用意することです。これにより、モジュールレベルでコンテンツを翻訳できます。

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations';

await initializeGTSPA({
  ...gtConfig,
  loadTranslations,
});

await import('./main'); // GTの準備が完了した後にアプリをレンダリングする
```

<Accordions>
  <Accordion title="CommonJS を使用していますか？">
    CommonJS はトップレベルの await をサポートしていません。初期化処理は非同期の起動関数でラップし、その後でアプリケーションを動的に import してください。これにより、モジュールレベルの [`t()`](/docs/react/reference/functions/t-function) 呼び出しに必要な非同期の境界を維持できます。

    ```js title="src/index.js"
    const { initializeGTSPA } = require('gt-react');
    const gtConfig = require('../gt.config.json');

    async function loadTranslations(locale) {
      try {
        return require(`./_gt/${locale}.json`);
      } catch (error) {
        console.warn(`No translations found for ${locale}`);
        return {};
      }
    }

    async function start() {
      await initializeGTSPA({
        ...gtConfig,
        loadTranslations,
      });

      await import('./main');
    }

    start().catch(console.error);
    ```

    <Callout type="warn">
      **警告:** 初期化前に `main` を require しないでください。先に require すると、翻訳の準備が整う前にモジュールレベルの [`t()`](/docs/react/reference/functions/t-function) 呼び出しが評価されます。
    </Callout>
  </Accordion>
</Accordions>

```tsx title="src/main.tsx"
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>
);
```

Vite では、`index.html` の module script タグを更新し、新しいエントリを参照するようにします。`src` を `/src/main.tsx` から `/src/index.ts` に変更してください。

```html title="index.html"
<!-- <script type="module" src="/src/main.tsx"></script> -->
<script type="module" src="/src/index.ts"></script>
```

[`initializeGTSPA`](/docs/react/reference/config#initialize-spa) は起動時に一度だけ実行され、この設定はアプリの実行中は変更できません。これが完了すると、どのモジュールからでも翻訳を取得できます。**アプリを provider でラップする必要はありません。**

<Accordions>
  <Accordion title="Create React App を使用していますか？">
    Create React App では `src/` 外からの import がブロックされ、トップレベルの `await` も有効になっていません。CLI 用にルートの `gt.config.json` はそのままにし、既存の `src/index.tsx` エントリを `src/main.tsx` にリネームしてから、この新しいエントリを作成してください。

    ```ts title="src/index.ts"
    import { initializeGTSPA } from 'gt-react';
    import loadTranslations from './loadTranslations';

    async function start() {
      await initializeGTSPA({
        defaultLocale: 'en',
        locales: ['es', 'fr', 'ja'],
        loadTranslations,
      });

      await import('./main');
    }

    start().catch(console.error);
    ```

    言語を追加または削除する際は、これらのロケール値を常にルート設定と同期させてください。`public/index.html` は変更しないでください。Create React App はすでに `src/index` を読み込みます。
  </Accordion>
</Accordions>

<Callout type="info">
  **ヒント:** compiler と開発用認証情報を追加するには、[SPA translations を使った開発](/docs/react/guides/developing-spa-translations) に従ってください。
</Callout>

### 5. 翻訳用にコンテンツをマークする

次に、翻訳したいテキストを **[`<T>`](/docs/react/reference/components/t)** コンポーネントで囲みます。[`<T>`](/docs/react/reference/components/t) は &quot;translate&quot; の略です:

```tsx title="src/components/Welcome.tsx"
import { T } from 'gt-react';

export default function Welcome() {
  return (
    <main>
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

[`<T>`](/docs/react/reference/components/t) の中では、必要に応じて JSX を必要な範囲だけ囲めます。中に含まれるものは、テキスト、ネストされた要素、フォーマットも含めて、すべて 1 つの単位として翻訳されます。

React コンポーネントの外にある文字列には、**[`t()`](/docs/react/reference/functions/t-function)** を使用します。[`initializeGTSPA()`](/docs/react/reference/config#initialize-spa) はアプリの他の部分より先に翻訳を読み込むため、モジュールレベルでも動作します:

```ts title="src/navigation.ts"
import { t } from 'gt-react';

export const navigation = [
  { label: t('Home'), href: '/' },
  { label: t('About'), href: '/about' },
];
```

### 6. 言語切り替え機能を追加する

ユーザーが言語を切り替えられるように、**[`<LocaleSelector>`](/docs/react/reference/components/locale-selector)** を追加します:

```tsx title="src/components/Welcome.tsx"
import { T, LocaleSelector } from 'gt-react';

export default function Welcome() {
  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

[`LocaleSelector`](/docs/react/reference/components/locale-selector) は、`gt.config.json` で指定した言語を表示するドロップダウンをレンダリングします。

ユーザーが言語を選択すると、`gt-react` はその選択を `generaltranslation.locale` クッキーに保存し、ページを再読み込みします。その後 [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) が再実行され、アプリがレンダリングされる前に新しいロケールの翻訳が読み込まれます。

### 7. 認証して翻訳する

翻訳を始める前に、General Translation に認証してください。

```bash
npx gt auth
```

画面の案内に従ってアカウントを作成するか、ログインします。キーの種類を尋ねられたら、本番用のキーを選択します。このコマンドにより APIキー と project ID が生成され、プロジェクトルートの `.env.local` に追加されます：

```bash title=".env.local"
GT_PROJECT_ID="your-project-id"
GT_API_KEY="gtx-api-your-production-key"
```

<Callout type="warn">
  **警告:** `.env.local` をコミットしたり、ブラウザ側のコードで `GT_API_KEY` を公開したりしないでください。
</Callout>

次に、設定されているすべてのロケール向けの翻訳ファイルを生成するため、`translate` コマンドを実行します。

```bash
npx gt translate
```

CLI はアプリをスキャンし、コンテンツを翻訳して、その結果を `gt.config.json` で指定した `output` パスに書き込みます。ソースコンテンツを変更したら、再度実行してください。

### 8. 実行して確認する

アプリケーションでサンプルコンポーネントをレンダリングします:

```tsx title="src/App.tsx"
import Welcome from './components/Welcome';

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

アプリケーションの開発サーバーを起動し (例: Vite なら `npm run dev`) 、ローカル URL を開いて `es`、`fr`、`ja` のいずれかを選択します。ページが再読み込みされ、見出しに選択した言語の翻訳が表示されることを確認してください。

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

<Accordions>
  <Accordion title="ドロップダウンを使っても言語が切り替わりません">
    ブラウザのクッキーが有効であること、選択したロケールが `gt.config.json` に含まれていること、アプリケーションのエントリモジュールが読み込まれる前に [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) が解決されることを確認してください。
  </Accordion>

  <Accordion title="一部の翻訳が不正確です">
    曖昧なテキストは、不正確な翻訳につながることがあります。たとえば、&quot;apple&quot; は果物を指す場合もあれば、会社を指す場合もあります。意味が伝わりやすくなるように、`$context` プロパティを追加してください。

    ```jsx
    <T $context="the technology company">Apple</T>
    ```

    [`<T>`](/docs/react/reference/components/t) と [`useGT()`](/docs/react/reference/hooks/use-gt) はどちらも `$context` オプションに対応しています。
  </Accordion>
</Accordions>

## Next steps

- /docs/react/guides/developing-spa-translations
- /docs/react/guides/translating-jsx
- /docs/react/guides/managing-locales
- /docs/react/guides/storing-translations

## Sitemap

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