# gt-react: General Translation React SDK: React クイックスタート
URL: https://generaltranslation.com/ja/docs/react.mdx
---
title: React クイックスタート
description: 10分以内で React アプリに複数の言語を追加
---

このガイドを終えるまでに、React アプリで複数の言語のコンテンツを表示し、ユーザーが操作できる言語切り替え機能も実装できるようになります。

**前提条件:**

* React アプリ (Vite、Create React App、または同様のもの) 
* Node.js 18+

<Callout type="info">
  **自動でセットアップしたいですか？** `npx gt@latest` を実行すると、[セットアップウィザード](/docs/cli/init) を使ってすべて設定できます。このガイドでは手動でのセットアップを扱います。
</Callout>

***

## ステップ 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": "public/_gt/[locale].json"
    }
  }
}
```

* **`defaultLocale`** — アプリを記述している言語 (ソース言語) です。
* **`locales`** — 翻訳先にしたいロケールです。[supported locales list](/docs/platform/supported-locales) から任意に選択できます。
* **`files`** — 翻訳ファイルの保存先を CLI に指定します。`output` パスは、`loadTranslations` 関数 (ステップ 3) の import パスと一致させてください。

<Callout type="info">
  **Vite を使っていますか?** 出力パスは `"public/_gt/[locale].json"` ではなく `"src/_gt/[locale].json"` に設定してください。Vite は翻訳ファイルをモジュールとして import するため、`public/` ではなく `src/` 内に配置する必要があります。
</Callout>

***

## ステップ3: 翻訳ローダーを作成する

`gt-react` は完全にクライアントで動作するため、runtime に翻訳ファイルを読み込む関数が必要です。`loadTranslations` ファイルを作成します:

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

この関数は、`public/_gt/` ディレクトリから JSON の翻訳ファイルを読み込みます。これらのファイルは、`npx gt translate` を実行すると CLI によって生成されます。

<Accordions>
  <Accordion title="Vite を使用していますか？">
    Vite の翻訳ファイルは `src/_gt/` にあるため (ステップ 2 を参照) 、import パスを更新してください:

    ```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 {};
      }
    }
    ```
  </Accordion>

  <Accordion title="Create React App を使用していますか？">
    CRA の webpack 設定では、`src/` の外からの動的 `import()` はブロックされます。代わりに `fetch()` を使用してください:

    ```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('Not found');
        return await response.json();
      } catch (error) {
        console.warn(`No translations found for ${locale}`);
        return {};
      }
    }
    ```
  </Accordion>
</Accordions>

***

## ステップ 4: アプリに GTProvider を追加する

**`GTProvider`** コンポーネントを使うと、アプリ全体で翻訳を利用できるようになります。アプリのルートでラップします:

```tsx title="src/App.tsx"
import { GTProvider } from 'gt-react';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations';

export default function App() {
  return (
    <GTProvider config={gtConfig} loadTranslations={loadTranslations}>
      {/* アプリのコンテンツ */}
    </GTProvider>
  );
}
```

`GTProvider` は、設定と翻訳ローダーを props として受け取ります。ロケールの状態を管理し、すべての子コンポーネントで翻訳を使えるようにします。

<Accordions>
  <Accordion title="Create React App を使っていますか？">
    CRA では `src/` 内のファイルしか import できないため、`import gtConfig from '../gt.config.json'` は失敗します。`gt.config.json` を `src/` にコピーするか、設定を直接インラインで記述してください:

    ```tsx title="src/App.tsx"
    import { GTProvider } from 'gt-react';
    import loadTranslations from './loadTranslations';

    export default function App() {
      return (
        <GTProvider
          config={{
            defaultLocale: 'en',
            locales: ['es', 'fr', 'ja'],
          }}
          loadTranslations={loadTranslations}
        >
          {/* アプリのコンテンツ */}
        </GTProvider>
      );
    }
    ```
  </Accordion>
</Accordions>

***


## ステップ 5: コンテンツを翻訳対象としてマークする

次に、翻訳したいテキストを **`<T>`** コンポーネントで囲みます。`<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>` の中には、必要な範囲だけ JSX を自由に囲めます。中に含まれるものはすべて — テキスト、ネストされた要素、書式指定まで含めて — ひとまとまりで翻訳されます。

***


## ステップ6: 言語切り替えを追加する

ユーザーが言語を切り替えられるよう、**`<LocaleSelector>`** を追加します:

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

export default function Welcome() {
  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>アプリへようこそ</h1>
        <p>このコンテンツは自動的に翻訳されます。</p>
      </T>
    </main>
  );
}
```

`LocaleSelector` は、`gt.config.json` の言語が一覧表示されるドロップダウンをレンダリングします。

***


## ステップ7: 環境変数を設定する (任意)

開発環境で翻訳を確認するには、General Translation の API キーが必要です。これにより、**on-demand 翻訳**が有効になり、開発中のアプリでコンテンツがリアルタイムに翻訳されます。

使用しているバンドラーに応じた正しいプレフィックスで **`.env.local`** ファイルを作成します:

<Tabs items={["Vite", "Create React App"]}>
  <Tab value="Vite">
    ```bash title=".env.local"
    VITE_GT_API_KEY="your-dev-api-key"
    VITE_GT_PROJECT_ID="your-project-id"
    ```
  </Tab>

  <Tab value="Create React App">
    ```bash title=".env.local"
    REACT_APP_GT_API_KEY="your-dev-api-key"
    REACT_APP_GT_PROJECT_ID="your-project-id"
    ```
  </Tab>
</Tabs>

無料のキーは、[dash.generaltranslation.com](https://dash.generaltranslation.com/signup)で取得するか、次を実行してください。

```bash
npx gt auth
```

<Callout type="warn">
  開発では、`gtx-dev-` で始まるキーを使用してください。本番用キー (`gtx-api-`) は CI/CD でのみ使用します。

  Vite や CRA のようなクライアント側バンドラでは、環境変数をブラウザに公開するために特定のプレフィックス (`VITE_` または `REACT_APP_`) を付ける必要があります。プレフィックスのない `GT_API_KEY` は runtime では利用できません。
</Callout>

<Accordions>
  <Accordion title="API キーなしで gt-react を使えますか？">
    はい。API キーがなくても、`gt-react` は標準的な i18n ライブラリとして動作します。開発中の on-demand 翻訳は利用できませんが、次のことは引き続き可能です。

    * 独自の翻訳ファイルを手動で用意する
    * すべてのコンポーネント (`<T>`、`<Var>`、`LocaleSelector` など) を使う
    * `npx gt generate` を実行して翻訳ファイルのテンプレートを作成し、その後自分で翻訳する
  </Accordion>
</Accordions>

***

## ステップ 8: 動作を確認する

開発サーバーを起動します。

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm run dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dev
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun dev
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dev
    ```
  </Tab>
</Tabs>

アプリを開き、言語ドロップダウンで言語を切り替えます。コンテンツが翻訳されて表示されるはずです。

<Callout type="info">
  開発時は、翻訳が on-demand で行われます。そのため、新しい言語に初めて切り替える際には、短い読み込み状態が表示されることがあります。本番環境では翻訳が事前生成されるため、すぐに読み込まれます。
</Callout>

***

## ステップ 9: JSX 以外の文字列も翻訳する

`placeholder` 属性や `aria-label` の値、`alt` テキストのようなプレーンな文字列には、**`useGT`** フックを使用します。

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

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

  return (
    <form>
      <input
        placeholder={gt('Enter your email')}
        aria-label={gt('Email input field')}
      />
      <button type="submit">{gt('Send')}</button>
    </form>
  );
}
```

***


## ステップ10: 本番環境にデプロイする

本番環境では、翻訳はビルド時に事前生成されるため、リアルタイムのAPI呼び出しは発生しません。ビルドスクリプトに `translate` コマンドを追加します。

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

ホスティングプロバイダー (Vercel、Netlify など) で、**本番環境**の環境変数を設定します：

```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```

<Callout type="warn">
  本番用のキーは `gtx-api-` で始まります (`gtx-dev-` ではありません) 。[dash.generaltranslation.com](https://dash.generaltranslation.com) から取得してください。`GT_API_KEY` を公開しないでください。
</Callout>

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

***


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

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

    * [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="開発環境では翻訳に時間がかかる">
    これは想定どおりの挙動です。開発環境では、翻訳は on-demand で行われます (コンテンツは API 経由でリアルタイムに翻訳されます) 。この遅延は**本番環境では発生しません**。すべての翻訳は `npx gt translate` によって事前生成されます。
  </Accordion>

  <Accordion title="一部の翻訳が不正確">
    テキストが曖昧だと、不正確な翻訳につながることがあります。たとえば、&quot;apple&quot; は果物を指す場合もあれば、企業を指す場合もあります。意味を補足するために `context` prop を追加してください。

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

    `<T>` と `useGT()` はどちらも `context` オプションをサポートしています。
  </Accordion>
</Accordions>

***

## 次のステップ

* [**`<T>` コンポーネントガイド**](/docs/react/guides/t) — 変数、複数形表現、高度な翻訳パターンについて学ぶ
* [**文字列翻訳ガイド**](/docs/react/guides/strings) — `useGT` を詳しく解説
* [**変数コンポーネント**](/docs/react/guides/variables) — `<Var>`、`<Num>`、`<Currency>`、`<DateTime>` を使って動的な内容を扱う
* [**複数形処理**](/docs/react/api/components/plural) — `<Plural>` コンポーネントで複数形を扱う
* [**本番環境へのデプロイ**](/docs/react/tutorials/quickdeploy) — CI/CD のセットアップ、キャッシュ、パフォーマンス最適化
* [**共有文字列**](/docs/react/guides/shared-strings) — `msg()` を使って配列、設定オブジェクト、共有データ内のテキストを翻訳する