# General Translation React SDKs (gt-react, gt-next): 設定 URL: https://generaltranslation.com/ja/docs/react/reference/config.mdx --- title: 設定 description: 共有の `gt.config.json` ファイルとランタイム初期化を使って、React エコシステム全体で General Translation を設定します。`gt.config.json` の API リファレンスです。 --- 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` アプリのセットアップは、ライブラリを初期化し、アクティブなロケールの翻訳を読み込み、コンポーネントツリーを [``](/docs/react/reference/components/gt-provider) でラップする、3 つの手順で構成されます。 * サーバーサイドレンダリングのセットアップでは [`initializeGT`](#initialize) で**初期化**します。シングルページアプリでは [`initializeGTSPA`](#initialize-spa) を使用します。これは、クッキーとブラウザーからアクティブなロケールも判定します。 * [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot) を使って、アクティブなロケールの**翻訳を読み込み**ます。 * [``](/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` | いいえ | — | どちらの関数も以下のフィールドを受け取ります。オプションは共通ですが、ブラウザのロケール検出を行うのは `initializeGTSPA` のみです。 | オプション | 説明 | 型 | 任意 | デフォルト | | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------- | -- | ----------------- | | `defaultLocale` | 翻訳元のソースロケール。 | `string` | はい | `en` | | `locales` | サポートされている対象ロケール。 | `string[]` | はい | `[defaultLocale]` | | `locale` | 明示的に指定する初期ロケール。設定すると検出をスキップします。 | `string` | はい | 自動検出 | | [`loadTranslations`](/docs/react/reference/functions/load-translations) | ロケールに対応する翻訳を返すローダー。ドキュメント: [`loadTranslations`](/docs/react/reference/functions/load-translations)。 | `(locale: string) => Promise` | はい | GT CDN | | [`loadDictionary`](/docs/react/reference/functions/load-dictionary) | ロケールに対応する辞書を返すローダー。ドキュメント: [`loadDictionary`](/docs/react/reference/functions/load-dictionary)。 | `(locale: string) => Promise` | はい | — | | `dictionary` | `loadDictionary` の代わりに使うインライン辞書。 | `object` | はい | — | | `projectId` | CDN と開発時の翻訳に使用する General Translation Project ID。 | `string` | はい | — | | `devApiKey` | オンデマンド翻訳とホットリロード用の開発用 API キー。 | `string` | はい | — | | `apiKey` | 本番用の API キー。ブラウザでは `devApiKey` を優先してください。 | `string` | はい | — | | `cacheUrl` | カスタムの翻訳ホスト。`null` にするとリモート読み込みを無効にします。 | `string \| null` | はい | GT CDN | | `runtimeUrl` | 開発時の翻訳に使用するランタイム translation host。 | `string \| null` | はい | GT runtime | | `customMapping` | ロケールのエイリアスとプロパティのオーバーライド。 | `object` | はい | — | | `region` | リージョン対応の書式設定に使用する初期リージョンコード。 | `string` | はい | — | | `enableI18n` | コンテンツを翻訳します。`false` の場合はソースロケールを表示します。 | `boolean` | はい | `true` | | `htmlTagOptions` | ロケール変更時に `` の `lang` 属性と `dir` 属性を同期するかどうか。 | `object` | はい | — | ### `initializeGT` [#initialize] **型** `(config) => void` · **必須** ブラウザのロケール検出を行わずに、設定と翻訳キャッシュを初期化します。フレームワークがリクエストのロケールと翻訳を提供する、サーバーサイドでレンダリングされるセットアップで使用します。 ```tsx initializeGT({ ...gtConfig, loadTranslations, }); ``` ### `initializeGTSPA` [#initialize-spa] **型** `(config) => Promise` · **必須** シングルページアプリで `gt-react` を初期化します。初回レンダーの前に、一度だけ呼び出してください。翻訳キャッシュを作成し、cookie とブラウザ設定からアクティブなロケールを判定して、翻訳を事前読み込みします。ブラウザエントリでのみ使用できます。 ```tsx await initializeGTSPA({ ...gtConfig, loadTranslations, locale: gtConfig.defaultLocale, }); ``` 環境からロケールを解決するため、`initializeGTSPA` は Promise を返します。レンダリングする前に await してください。ロケールの変更時に `` 要素の `lang` 属性と `dir` 属性を更新するかどうかは、`htmlTagOptions` で制御できます: ```tsx await initializeGTSPA({ ...gtConfig, loadTranslations, htmlTagOptions: { updateHtmlLangTag: true, // デフォルト: true updateHtmlDirTag: true, // デフォルト: true }, }); ``` ## `gt.config.json` [#config-file] `gt.config.json` は project root にあり、CLI と共有するロケールおよびファイル設定を保持します。これを import し、各フィールドを初期化時に渡します。 | キー | 説明 | 型 | 任意 | デフォルト | | ------------------------------------------ | --------------------------------- | ---------- | -- | ---------- | | [`projectId`](#project-id) | General Translation の project ID。 | `string` | はい | — | | [`defaultLocale`](#default-locale) | ソースロケール。 | `string` | はい | `en` | | [`locales`](#locales) | 対象ロケール。 | `string[]` | はい | — | | [`customMapping`](#custom-mapping) | ロケールの aliases とプロパティのオーバーライド。 | `object` | はい | — | | [`cacheUrl`](#cache-url) | キャッシュ済み翻訳のベース URL。 | `string` | はい | GT CDN | | [`runtimeUrl`](#runtime-url) | ランタイム (開発用) 翻訳のベース URL。 | `string` | はい | GT runtime | | [`stageTranslations`](#stage-translations) | 翻訳を本番環境に反映する前にレビューを必須にします。 | `boolean` | はい | `false` | | [`files`](#files) | ローカル翻訳ファイルのパスと解析フラグ。 | `object` | はい | — | | [`_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 コードで指定します。 ### `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) を参照してください。 ### `_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 ( {children} ); } ```