# General Translation React SDKs (gt-react, gt-next, gt-react-native): 設定
URL: https://generaltranslation.com/ja/docs/react/reference/config.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 共有の `gt.config.json` ファイルとランタイム初期化を使って、React エコシステムを設定します。`gt.config.json` のリファレンスです。

General Translation の設定は 2 か所で行います。1 つは、[CLI](/docs/cli/reference/config) と共有するロケールやファイル設定を保持する `gt.config.json` ファイル、もう 1 つは、first render の前にその設定を読み込むランタイムのセットアップ手順です。`gt.config.json` ファイルは React エコシステム全体で共通ですが、ランタイムのセットアップはフレームワークごとに異なります。

*このページの `gt.config.json` リファレンスは、`gt-react`、`gt-next`、`gt-tanstack-start`、`gt-react-native` で共通です。初期化関数 ([`initializeGT`](#initialize)、[`initializeGTSPA`](#initialize-spa)) は `gt-react` 用です。`gt-tanstack-start` と `gt-react-native` でも `initializeGT` を使用します。*

*注: `gt-next` はこれらの初期化関数を使用しません。代わりに、`withGTConfig` プラグインを通じて設定を読み込みます。詳しくは Next.js セクションを参照してください。*

## 概要 [#overview]

サーバーサイドでレンダリングされる `gt-react` アプリのセットアップは、ライブラリを初期化し、アクティブなロケールの翻訳を読み込み、コンポーネントツリーを [`<GTProvider>`](/docs/react/reference/components/gt-provider) でラップする、3 つの手順で構成されます。

* サーバーサイドレンダリングのセットアップでは [`initializeGT`](#initialize) で**初期化**します。シングルページアプリでは [`initializeGTSPA`](#initialize-spa) を使用します。これは、クッキーとブラウザーからアクティブなロケールも判定します。
* [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot) を使って、アクティブなロケールの**翻訳を読み込み**ます。
* [`<GTProvider>`](/docs/react/reference/components/gt-provider) を使って、ロケールと翻訳をコンポーネントに**提供**します。

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

const loadTranslations = (locale: string) =>
  import(`../_gt/${locale}.json`).then((m) => m.default);

initializeGT({ ...gtConfig, loadTranslations });

export async function loadRoot(request: Request) {
  const locale = parseLocale(request);
  return {
    locale,
    translations: await getTranslationsSnapshot(locale),
  };
}
```

`gt.config.json` ファイルには、共有のロケール設定とファイル設定をまとめて記述します。初期化呼び出しと CLI はどちらも同じ値を参照するため、1 か所にまとめておいてください。

## 初期化 [#initialization]

| 関数                                   | 説明                                            | 型          | 任意  | デフォルト |
| ------------------------------------ | --------------------------------------------- | ---------- | --- | ----- |
| [`initializeGT`](#initialize)        | ブラウザのロケール検出を行わずに初期化します。サーバーサイドレンダリングのアプリ向けです。 | `function` | いいえ | —     |
| [`initializeGTSPA`](#initialize-spa) | ブラウザのロケール検出を含めて、シングルページアプリを初期化します。            | `function` | いいえ | —     |

どちらの関数も以下の共通フィールドを受け取ります。

| オプション                                                                   | 説明                                                                                                  | 型                                      | 任意 | デフォルト             |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------- | -- | ----------------- |
| `defaultLocale`                                                         | 翻訳元のソースロケール。                                                                                        | `string`                               | はい | `en`              |
| `locales`                                                               | サポートされている対象ロケール。                                                                                    | `string[]`                             | はい | `[defaultLocale]` |
| [`loadTranslations`](/docs/react/reference/functions/load-translations) | ロケールに対応する翻訳を返すローダー。ドキュメント: [`loadTranslations`](/docs/react/reference/functions/load-translations)。 | `(locale: string) => Promise<unknown>` | はい | GT CDN            |
| [`loadDictionary`](/docs/react/reference/functions/load-dictionary)     | ロケールに対応する辞書を返すローダー。ドキュメント: [`loadDictionary`](/docs/react/reference/functions/load-dictionary)。     | `(locale: string) => Promise<unknown>` | はい | —                 |
| `dictionary`                                                            | [`loadDictionary`](/docs/react/reference/functions/load-dictionary) の代わりに使うインライン辞書。                 | `object`                               | はい | —                 |
| `projectId`                                                             | CDN と開発時の翻訳に使用する General Translation プロジェクト ID。                                                     | `string`                               | はい | —                 |
| `devApiKey`                                                             | オンデマンド翻訳とホットリロード用の開発用 API キー。                                                                       | `string`                               | はい | —                 |
| `apiKey`                                                                | 本番用の API キー。ブラウザでは `devApiKey` を優先してください。                                                           | `string`                               | はい | —                 |
| `cacheUrl`                                                              | カスタムの翻訳ホスト。`null` にするとリモート読み込みを無効にします。                                                              | `string \| null`                       | はい | GT CDN            |
| `runtimeUrl`                                                            | 開発時の翻訳に使用するランタイム translation host。                                                                  | `string \| null`                       | はい | GT runtime        |
| `customMapping`                                                         | ロケールのエイリアスとプロパティの上書き設定。                                                                             | `object`                               | はい | —                 |
| [`_tagIds`](#tag-ids)                                                   | 各 [`<T>`](/docs/react/reference/components/t) 翻訳ハッシュを `data-_gt-hash` DOM 属性として公開します。               | `boolean`                              | はい | `false`           |

### `initializeGT` [#initialize]

**型** `(config) => void` · **必須**

ブラウザのロケール検出を行わずに、設定と翻訳キャッシュを初期化します。フレームワークがリクエストのロケールと翻訳を提供する、サーバーサイドでレンダリングされるセットアップで使用します。

```tsx
initializeGT({
  ...gtConfig,
  loadTranslations,
});
```

### `initializeGTSPA` [#initialize-spa]

**型** `(config) => Promise<void>` · **必須**

シングルページアプリで `gt-react` を初期化します。初回レンダーの前に、一度だけ呼び出してください。翻訳キャッシュを作成し、cookie とブラウザ設定からアクティブなロケールを判定して、翻訳を事前読み込みします。ブラウザエントリでのみ使用できます。

ブラウザ専用の次のフィールドも受け入れます。

| オプション                               | 説明                                         | 型                                                             | 任意 | デフォルト  |
| ----------------------------------- | ------------------------------------------ | ------------------------------------------------------------- | -- | ------ |
| `locale`                            | 明示的な初期ロケール。設定すると検出をスキップします。                | `string`                                                      | はい | 検出済み   |
| `region`                            | リージョン対応フォーマット用の初期リージョンコード。                 | `string`                                                      | はい | —      |
| `enableI18n`                        | コンテンツを翻訳します。`false` の場合、ソースロケールをレンダリングします。 | `boolean`                                                     | はい | `true` |
| [`htmlTagOptions`](#htmltagoptions) | HTML 要素を自動更新しない互換性フィールド。                   | `{ updateHtmlLangTag?: boolean; updateHtmlDirTag?: boolean }` | はい | —      |

```tsx
await initializeGTSPA({
  ...gtConfig,
  loadTranslations,
  locale: gtConfig.defaultLocale,
});
```

環境からロケールを解決するため、`initializeGTSPA` は Promise を返します。レンダリングする前に await してください。ロケールの変更時に、アプリで `<html>` 要素の `lang` 属性と `dir` 属性を更新してください。

#### `htmlTagOptions`

**型** `{ updateHtmlLangTag?: boolean; updateHtmlDirTag?: boolean }` · **任意**

`initializeGTSPA` で受け付ける、ブラウザ専用の互換性フィールドです。これを渡しても、ロケールの変更時に `<html>` 要素の `lang` 属性や `dir` 属性が自動的に更新されることはありません。これらの属性はアプリ内で更新してください。

## `gt.config.json` [#config-file]

`gt.config.json` は project root にあり、CLI と共有するロケールおよびファイル設定を保持します。これを import し、各フィールドを初期化時に渡します。

| キー                                         | 説明                                                                                    | 型          | 任意 | デフォルト      |
| ------------------------------------------ | ------------------------------------------------------------------------------------- | ---------- | -- | ---------- |
| [`projectId`](#project-id)                 | General Translation プロジェクト ID。                                                     | `string`   | はい | —          |
| [`defaultLocale`](#default-locale)         | ソースロケール。                                                                              | `string`   | はい | `en`       |
| [`locales`](#locales)                      | 対象ロケール。                                                                               | `string[]` | はい | —          |
| [`localeRouting`](#locale-routing)         | パス名にアクティブなロケールを保持します。                                                                 | `boolean`  | はい | フレームワーク固有  |
| [`customMapping`](#custom-mapping)         | ロケールのエイリアスとプロパティの上書き設定。                                                               | `object`   | はい | —          |
| [`cacheUrl`](#cache-url)                   | キャッシュ済み翻訳のベース URL。                                                                    | `string`   | はい | GT CDN     |
| [`runtimeUrl`](#runtime-url)               | ランタイム (開発用) 翻訳のベース URL。                                                               | `string`   | はい | GT runtime |
| [`stageTranslations`](#stage-translations) | 翻訳を本番環境に反映する前にレビューを必須にします。                                                            | `boolean`  | はい | `false`    |
| [`files`](#files)                          | ローカル翻訳ファイルのパスと解析フラグ。                                                                  | `object`   | はい | —          |
| [`_tagIds`](#tag-ids)                      | 各 [`<T>`](/docs/react/reference/components/t) 翻訳ハッシュを `data-_gt-hash` DOM 属性として公開します。 | `boolean`  | はい | `false`    |
| [`_versionId`](#version-id)                | 内部の翻訳バージョン識別子。編集しないでください。                                                             | `string`   | はい | —          |

### `projectId` [#project-id]

**型** `string` · **任意**

General Translation のプロジェクトを一意に識別する ID です。CDN 配信およびオンデマンドの開発時の翻訳に必要です。

### `defaultLocale` [#default-locale]

**型** `string` · **任意** · **デフォルト** `en`

UIの記述に使用するソースロケールです。翻訳が存在しない場合のフォールバックとして使用されます。

### `locales` [#locales]

**型** `string[]` · **任意**

プロジェクトでサポートする対象ロケールを、`['es', 'fr']` のような BCP 47 コードで指定します。

### `localeRouting` [#locale-routing]

**型** `boolean` · **任意** · **デフォルト** フレームワーク固有

TanStack Start における、ロケールのプレフィックス付き URL を制御します。これはオプトインで、デフォルトは `false` です。このオプションでルートが定義されるわけではありません。TanStack Router がプレフィックスなしとロケールのプレフィックス付きの両方の URL を受け入れるように、任意の `/{-$locale}` パスパラメータまたは URL リライトを設定してください。[TanStack Start セットアップガイド](/docs/react/tanstack-start/setup#locale-routing)を参照してください。有効にすると、[`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) はサポートされている最初のパスセグメントを優先し、デフォルトロケールには引き続きプレフィックスが付かず、クライアントでロケールを変更すると対応するパス名で再読み込みされます。

Next.js では、ルーティングは [`createNextMiddleware({ localeRouting })`](/docs/react/nextjs/reference/functions/create-next-middleware) で個別に設定され、デフォルトは `true` です。このオプションは、通常の React SPAs や React Native には影響しません。

### `customMapping` [#custom-mapping]

**Type** `object` · **任意**

ロケールの aliases とプロパティの上書き設定です。ロケールの解決方法や表示方法の名称変更・カスタマイズに使用します。

### `cacheUrl` [#cache-url]

**型** `string` · **省略可能** · **デフォルト** GT CDN

キャッシュ済みの翻訳を取得するためのベース URL です。独自のホストを指すように設定するか、初期化時に `null` を渡してリモートからの読み込みを無効にします。

### `runtimeUrl` [#runtime-url]

**型** `string` · **任意** · **デフォルト** GT runtime

ランタイム翻訳サービスのベース URL です。開発時の翻訳にのみ適用されます。

### `stageTranslations` [#stage-translations]

**型** `boolean` · **任意** · **デフォルト** `false`

`true` の場合、`gt` ツールは翻訳をレビューが必要な状態としてマークします。これらの翻訳は、[`gt translate`](/docs/cli/reference/commands/translate) を通じて本番環境にデプロイする前に承認されている必要があります。

### `files` [#files]

**型** `object` · **任意**

クラウドではなくローカルに翻訳を保存する場合の、書き込み先を指定します。`files.gt.output` は `[locale]` を含むパステンプレートで、`files.gt.parsingFlags` はコンパイラがソースをどのように解析するかを制御します。

```json title="gt.config.json"
{
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json",
      "parsingFlags": {
        "enableAutoJsxInjection": true,
        "autoderive": true
      }
    }
  }
}
```

* `enableAutoJsxInjection` (`boolean`, default `false`) — ビルド時に、翻訳対象の JSX テキストを translation components で自動的にラップします。詳しくは [JSX の自動インジェクション](/docs/cli/guides/using-auto-jsx) を参照してください。
* `autoderive` (`boolean`, default `false`) — [`t()`](/docs/react/reference/functions/t-function)、`gt()`、および [`msg()`](/docs/react/reference/functions/msg) の呼び出し内の補間値を、自動的に [`derive()`](/docs/react/reference/functions/derive) 呼び出しとして扱います。詳しくは [autoderive](/docs/cli/guides/using-autoderive) を参照してください。

`files` の完全な schema については、[CLI 設定リファレンス](/docs/cli/reference/config) を参照してください。

## `_tagIds` [#tag-ids]

**Type** `boolean` · **任意** · **デフォルト** `false`

`gt-react`、`gt-next`、`gt-tanstack-start` でレンダリングされる [`<T>`](/docs/react/reference/components/t) および [`<Tx>`](/docs/react/nextjs/reference/components/tx) の出力に対する DOM ID タギングを有効にします。ローカライズ済みリプレイやコンテキスト内 QA などのツールは、`data-_gt-hash` 属性を使用して、レンダリングされたノードをその翻訳に対応付けます。

共有 config file で `_tagIds` を設定し、その config を [`initializeGT`](#initialize) または [`initializeGTSPA`](#initialize-spa) に渡します。`withGTConfig` プラグインは Next.js でも同じファイルを読み取ります。

```json title="gt.config.json"
{
  "_tagIds": true
}
```

値はリテラルの `true` でなければなりません。真偽値以外の truthy 値を含め、他の値を指定するとタグ付けは無効のままです。React Native は共有 config フィールドを受け入れますが、DOM へのタグ付けは行いません。

<Callout type="warn">
  **これを有効にするとラッパー要素が追加される場合があります。** `<span>` の injection は必要最小限に抑えられます。

  * **単一のホスト要素** (例: `<T><td>…</td></T>`) はインプレースで注釈付けされます。ラッパーは追加されないため、`<tr>`、`<select>`、`<ul>` などの制約がある親要素内でもマークアップは有効なままです。
  * **素のテキスト、フラグメント、または component のルート**には属性を持たせるホスト要素がないため、output はレイアウトに影響しない `display:contents` の `<span>` でラップされます。1 つ挿入されるのはこの場合だけです。
  * **何も render しない output** (`null`、`undefined`、真偽値、`''`、すべてのエントリが何も render しない array、または空のフラグメント) は変更されないため、空の `<span>` は生成されません。`0` と `NaN` はテキストを render するため、通常どおりタグ付けされることに注意してください。

  このマークアップ injection が、タグ付けがデフォルトで無効になっている理由です。実行するツールで hashes が必要な場合を除き、無効のままにしてください。
</Callout>

### `_versionId` [#version-id]

**型** `string` · **任意**

CLI が翻訳バージョンの追跡に使用する内部識別子です。これにより、以前の翻訳にロールバックできます。自動生成されるため、編集しないでください。

## 使用例 [#examples]

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

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

const loadTranslations = (locale: string) =>
  import(`../_gt/${locale}.json`).then((m) => m.default);

initializeGT({ ...gtConfig, loadTranslations });

export async function loadRoot(request: Request) {
  const locale = parseLocale(request);
  return {
    locale,
    translations: await getTranslationsSnapshot(locale),
  };
}

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

## Sitemap

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