# General Translation React SDKs (gt-react, gt-next, gt-react-native): React SPA クイックスタート
URL: https://generaltranslation.com/ja/docs/react/react-spa-quickstart.mdx
---
title: React SPA クイックスタート
description: 10 分以内で、General Translation を使ってシングルページの React アプリに複数言語対応を追加します。
related:
  links:
    - /docs/react/guides/developing-spa-translations
    - /docs/react/guides/translating-jsx
    - /docs/react/guides/managing-locales
    - /docs/react/guides/storing-translations

---

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

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

**前提条件:**

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

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

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

## クイックスタート [#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) と一致している必要があります。

<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 が生成します。

### 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>
);
```

次に、`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 でラップする必要はありません。**

<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` パスに書き込みます。ソースコンテンツを変更したら、再度実行してください。

以上で完了です。これでアプリは多言語対応になりました。🎉

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

<Accordions>
  <Accordion title="ドロップダウンを使っても言語が切り替わりません">
    `gt-react` は、ユーザーの言語設定を `generaltranslation.locale` という名前のクッキーに保存します。以前に別の言語でテストした場合、このクッキーが選択内容より優先されることがあります。クッキーを削除して、もう一度お試しください。

    * [Chrome](https://support.google.com/chrome/answer/95647)
    * [Firefox](https://support.mozilla.org/en-US/kb/delete-cookies-remove-info-websites-stored)
    * [Safari](https://support.apple.com/en-mn/guide/safari/sfri11471/16.0/mac/11.0)
  </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