# General Translation React SDKs (gt-react, gt-next): React クイックスタート
URL: https://generaltranslation.com/ja/docs/react/react-quickstart.mdx
---
title: React クイックスタート
description: General Translation を使って、サーバーサイドレンダリングされた React アプリに 10 分以内で複数の言語を追加できます。
related:
  links:
    - /docs/react/guides/translating-jsx
    - /docs/react/guides/translating-strings
    - /docs/react/guides/managing-locales
    - /docs/react/guides/formatting-variables

---

# React クイックスタート

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

**前提条件:**

* サーバーサイドレンダリングされた React アプリ (React Router またはカスタム SSR セットアップ) 
* Node.js 18+

<Callout type="info">
  **注:** アプリが Vite を使った完全なブラウザレンダリングである場合は、代わりに [React SPA クイックスタート](/docs/react/react-spa-quickstart) を参照してください。この方法では provider をまったく使いません。
</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` 関数 (ステップ 3) の import パスと一致している必要があります。

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

ロケールの翻訳ファイルを読み込む `loadTranslations` 関数を作成します。サーバーではレンダリング時に実行され、ファイルは `npx gt translate` を実行すると CLI によって生成されます。

```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) {
    return {};
  }
}
```

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

サーバーとクライアントの両方で読み込まれるファイルのモジュールスコープで、**`initializeGT`** を呼び出します。配置場所としては、root route またはレイアウトが自然です。これにより、設定と翻訳ローダーが一度だけ登録されます。設定はアプリの実行中は変更できません。

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

initializeGT({
  defaultLocale: gtConfig.defaultLocale,
  locales: gtConfig.locales,
  loadTranslations,
});
```

### 5. サーバーで翻訳を読み込む

root route の loader (または同等のサーバー handler) で、リクエストのロケールを判定し、**`getTranslationsSnapshot`** で翻訳スナップショットを取得して、その両方を **`<GTProvider>`** に渡します：

```tsx title="src/routes/root.tsx"
import {
  GTProvider,
  getTranslationsSnapshot,
  parseLocale,
} from 'gt-react';

// ルートのローダー内で（正確なAPIはフレームワークによって異なります）
export async function loader({ request }) {
  const locale = parseLocale(request); // [!code highlight]
  return {
    locale,
    translations: await getTranslationsSnapshot(locale), // [!code highlight]
  };
}

export default function Root({ children }) {
  const { locale, translations } = useLoaderData();
  return (
    <GTProvider locale={locale} translations={translations}>
      {children}
    </GTProvider>
  );
}
```

### 6. コンテンツを翻訳対象としてマークする

翻訳したいテキストはすべて **`<T>`** コンポーネントで囲みます。`<T>` は「translate」を表します。

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

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

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

export default function ContactForm() {
  const gt = useGT();
  return <input placeholder={gt('Enter your email')} />;
}
```

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

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

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

export default function Header() {
  return <LocaleSelector />;
}
```

ユーザーが言語を選択すると、`gt-react` はその選択内容を `generaltranslation.locale` クッキー に保存し、ページを再読み込みします。これにより、サーバーは新しいロケールですべてを再レンダリングします。

### 8. 環境変数を設定する (任意) 

オンデマンドの開発時翻訳はブラウザで実行されます。フレームワークの公開環境変数を使って、Project ID と開発用 API キーをクライアントコードで参照できるようにしてください。本番用の API キーは絶対に公開しないでください。

Vite では、`gt-react` がこれらの変数を自動的に読み取ります。

```bash title=".env.local"
VITE_GT_PROJECT_ID="your-project-id"
VITE_GT_DEV_API_KEY="your-dev-api-key"
```

他のフレームワークでは、そのフレームワークのクライアント向け環境変数の規約に従い、公開した値を `initializeGT` に渡してください。

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

```bash
npx gt auth
```

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

### 9. 本番環境にデプロイする

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

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

ホスティングプロバイダーで**本番用**環境変数を設定します。

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

<Callout type="warn">
  **警告:** Production keys は `gtx-api-` で始まります (`gtx-dev-` ではありません) 。[dash.generaltranslation.com](https://dash.generaltranslation.com) で取得してください。`GT_API_KEY` は絶対に公開しないでください。
</Callout>

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

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

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

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

    `<T>` と `useGT()` はどちらも `$context` オプションに対応しています。
  </Accordion>
</Accordions>
## Next steps

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