# General Translation React SDKs (gt-react, gt-next, gt-react-native): React クイックスタート
URL: https://generaltranslation.com/ja/docs/react/react-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 10 分足らずで、General Translation を使ってサーバーサイドレンダリングされた 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`](/docs/react/reference/functions/load-translations) 関数 (ステップ 3) の import パスと一致している必要があります。

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

ロケールの翻訳ファイルを読み込む [`loadTranslations`](/docs/react/reference/functions/load-translations) 関数を作成します。サーバーではレンダリング時に実行され、ファイルは [`npx gt translate`](/docs/cli/reference/commands/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`](/docs/react/reference/config#initialize)** を呼び出します。配置場所としては、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`](/docs/react/reference/functions/get-translations-snapshot)** で翻訳スナップショットを取得して、その両方を **[`<GTProvider>`](/docs/react/reference/components/gt-provider)** に渡します：

```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>`](/docs/react/reference/components/t)** コンポーネントで囲みます。[`<T>`](/docs/react/reference/components/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`](/docs/react/reference/hooks/use-gt)** フックを使用します：

```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>`](/docs/react/reference/components/locale-selector)** を追加します:

```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`](/docs/react/reference/config#initialize) に渡してください。

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

```bash
npx gt auth
```

<Callout type="warn">
  **警告:** 開発環境では、`gtx-dev-` で始まるキーを使用してください。本番用の API キー (`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.config.json` に含まれていること、セレクターが [`<GTProvider>`](/docs/react/reference/components/gt-provider) の配下でレンダリングされていることを確認してください。カスタムの [`_reload`](/docs/react/reference/components/gt-provider#reload) コールバックを指定している場合は、選択後に再読み込みまたはページ遷移が行われることを確認してください。
  </Accordion>

  <Accordion title="開発環境では翻訳が遅い">
    これは想定どおりの動作です。開発環境では、翻訳はオンデマンドで行われます (コンテンツは API 経由でリアルタイムに翻訳されます) 。この遅延は**本番環境では発生しません**。すべての翻訳は [`npx gt translate`](/docs/cli/reference/commands/translate) によって事前生成されます。
  </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/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables

## Sitemap

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