# General Translation React SDKs (gt-react, gt-next): 設定 URL: https://generaltranslation.com/ja/docs/react/nextjs/config.mdx --- title: 設定 description: "`gt-next/config` の `withGTConfig` プラグインを使って Next.js アプリで General Translation を設定する方法、そのオプション、ローカル翻訳と CDN 翻訳の違いについて説明します。`withGTConfig` の API リファレンスです。" --- `withGTConfig` は `gt-next` の設定プラグインです。これを `next.config` で Next.js の設定に適用すると、ビルド時に国際化を有効にできます。`gt.config.json` ファイルを読み込み、渡したオプションや環境変数とマージしたうえで、compiler、翻訳の読み込み、リクエスト処理を設定します。 このページでは、このプラグインとそのオプションについて説明します。共通の `gt.config.json` におけるロケールとファイルの設定については [`gt-react` 設定リファレンス](/docs/react/reference/config) を、CLI 側の `files` schema については [CLI 設定リファレンス](/docs/cli/reference/config) を参照してください。 ## 概要 [#overview] `gt-next/config` から `withGTConfig` をインポートし、Next.js の設定をラップします。オプションは第2引数として渡せますが、ほとんどのプロジェクトではロケール設定は代わりに `gt.config.json` に記述します。 ```ts title="next.config.ts" import { withGTConfig } from 'gt-next/config'; import type { NextConfig } from 'next'; const nextConfig: NextConfig = { // 既存のNext.js設定 }; export default withGTConfig(nextConfig, { defaultLocale: 'en', locales: ['es', 'fr', 'ja'], }); ``` `withGTConfig` は `next.config` で使用する必要があります。国際化をビルドに組み込むのは、ここだけです。 ## 仕組み [#how-it-works] * **設定の解決。** デフォルトでは、プラグインは `./gt.config.json` を読み込みます (`./.gt/gt.config.json` と `./.locadex/gt.config.json` も確認します) 。値は **渡したオプション > 環境変数 > `gt.config.json` > デフォルト値** の優先順位でマージされます。`gt.config.json` とオプションの両方に同じキーが設定されていて値が一致しない場合、ビルド時に競合エラーが発生するため、各値は一か所でのみ管理してください。 * **認証情報は環境変数から取得されます。** `projectId`、`apiKey`、`devApiKey` をオプションとして渡すことはできません。環境変数として設定してください ([認証情報](#credentials) を参照) 。 * **ロケールの標準化。** General Translation のサービスが有効な場合、ロケールコードは正規の BCP 47 形式に標準化され、無効なロケールはビルド時にエラーになります。 * **翻訳の配信。** [`loadTranslations`](/docs/react/reference/functions/load-translations) ファイルが見つかった場合、翻訳はバンドルから読み込まれます。見つからない場合は、General Translation CDN から取得されます。詳細は [ローカル翻訳と CDN 翻訳](#translations) を参照してください。 ## 認証情報 [#credentials] Project ID と API キーは、プラグインオプションではなく、必ず環境変数として設定してください。 | Variable | Description | | -------------------------------------------------- | ----------------------------------------------------- | | `GT_PROJECT_ID` (or `NEXT_PUBLIC_GT_PROJECT_ID`) | General Translation のプロジェクト ID。 | | `GT_API_KEY` | 本番用の API キー (プレフィックスは `gtx-api-`) 。CLI と本番ビルドで使用されます。 | | `GT_DEV_API_KEY` (or `NEXT_PUBLIC_GT_DEV_API_KEY`) | 開発用 API キー (プレフィックスは `gtx-dev-`) 。開発時のオンデマンド翻訳に使用します。 | *警告: 本番用の API キーに `NEXT_PUBLIC_` を絶対に付けないでください。また、開発用キーを本番環境に含めないでください。`NODE_ENV=production` で `GT_DEV_API_KEY` が存在すると、ビルドはエラーになります。* ## オプション [#options] すべてのオプションは省略可能です。ロケールのオプションは、ここではなく `gt.config.json` で設定するのが一般的です。 ### ロケールオプション [#locale-options] | オプション | 説明 | 型 | 任意 | デフォルト | | ---------------------------------------------------------------- | ---------------------------- | ---------- | -- | ------- | | [`defaultLocale`](#default-locale) | アプリの記述に使用されるソースロケール。 | `string` | はい | `en` | | [`locales`](#locales) | 翻訳先のロケール。 | `string[]` | はい | `[]` | | [`ignoreBrowserLocales`](#ignore-browser-locales) | 検出時にブラウザーの優先ロケールを無視します。 | `boolean` | はい | `false` | | [`disableInvalidLocaleWarning`](#disable-invalid-locale-warning) | 無効なリクエストロケールに関する警告を抑制します。 | `boolean` | はい | `false` | | [`description`](#description) | 翻訳の指針として使用される、アプリの自然言語による説明。 | `string` | はい | — | ### 翻訳配信 [#delivery-options] | オプション | 説明 | 型 | 任意 | デフォルト | | ------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------- | -- | ------------------ | | [`runtimeUrl`](#runtime-url) | General Translation API のベース URL。空文字列を指定するとランタイム翻訳が無効になります。 | `string \| null` | はい | GT runtime | | [`cacheUrl`](#cache-url) | キャッシュ済みの翻訳の URL。 | `string \| null` | はい | GT CDN | | [`cacheExpiryTime`](#cache-expiry-time) | ローカルにキャッシュされた翻訳の有効期限が切れるまでのミリ秒数。 | `number` | はい | `60000` | | [`loadTranslationsPath`](#load-translations-path) | カスタム `loadTranslations` ファイルのパス。 | `string` | はい | 自動解決 | | [`loadDictionaryPath`](#load-dictionary-path) | カスタム [`loadDictionary`](/docs/react/reference/functions/load-dictionary) ファイルのパス。 | `string` | はい | 自動解決 | | [`dictionary`](#dictionary) | dictionary ファイルのパス。 | `string` | はい | 自動解決 | | [`config`](#config-path) | `gt.config.json` ファイルのパス。 | `string` | はい | `./gt.config.json` | ### レンダリング [#rendering-options] | オプション | 説明 | 型 | 任意 | デフォルト | | ------------------------------------ | ----------------------------- | -------- | -- | ----- | | [`renderSettings`](#render-settings) | 読み込み中にランタイム翻訳をどのようにレンダリングするか。 | `object` | はい | 以下を参照 | ### パフォーマンス [#performance-options] | オプション | 説明 | 型 | 任意 | デフォルト | | --------------------------------------------------- | -------------------- | -------- | -- | ----- | | [`maxConcurrentRequests`](#max-concurrent-requests) | 同時実行する翻訳リクエストの最大数。 | `number` | はい | `100` | | [`maxBatchSize`](#max-batch-size) | 1バッチあたりの最大翻訳数。 | `number` | はい | `25` | | [`batchInterval`](#batch-interval) | バッチリクエスト間の間隔 (ミリ秒) 。 | `number` | はい | `50` | ### ビルドと統合 [#build-options] | オプション | 説明 | 型 | 任意 | デフォルト | | -------------------------------------------------- | --------------------------------------------------------------------- | ------------------- | -- | -------- | | [`experimentalCompilerOptions`](#compiler-options) | コンパイラプラグインの設定。 | `object` | はい | 以下を参照 | | [`headersAndCookies`](#headers-and-cookies) | カスタムのロケール header 名と cookie 名。 | `object` | はい | 以下を参照 | | [`getLocalePath`](#request-function-paths) | カスタムの [`getLocale`](/docs/node/reference/functions/get-locale) 関数のパス。 | `string` | はい | — | | [`getRegionPath`](#request-function-paths) | カスタムの `getRegion` 関数のパス。 | `string` | はい | — | | [`pathRegex`](#path-regex) | i18n ミドルウェアを、一致するパス名に限定します。 | `string` | はい | — | | [`eslint`](#eslint-options) | General Translation の ESLint 設定を生成します。 | `boolean` | はい | `true` | | [`eslintSeverity`](#eslint-options) | 生成される ESLint ルールの重要度。 | `'error' \| 'warn'` | はい | `'warn'` | | [`overwriteESLintConfig`](#eslint-options) | 既存の `eslint.config.mjs` を上書きします。 | `boolean` | はい | `false` | ### `defaultLocale` [#default-locale] **型** `string` · **任意** · **デフォルト** `en` アプリが記述されているソースロケールです。翻訳が存在しない場合のフォールバックとして使用されます。 ### `locales` [#locales] **型** `string[]` · **任意** · **デフォルト** `[]` 翻訳先のロケールです。未対応のロケールがリクエストされた場合は、まず最も近い一致先にフォールバックし、その後 `defaultLocale` にフォールバックします。[サポートされているロケール](/docs/platform/dashboard/reference/supported-locales) から選択してください。 ### `ignoreBrowserLocales` [#ignore-browser-locales] **型** `boolean` · **任意** · **デフォルト** `false` `true` の場合、ロケール検出時にブラウザーの `Accept-Language` の優先設定は無視されます。 ### `disableInvalidLocaleWarning` [#disable-invalid-locale-warning] **Type** `boolean` · **任意** · **デフォルト** `false` `true` にすると、無効なリクエストロケールに関する警告は表示されなくなります。 ### `description` [#description] **型** `string` · **省略可能** アプリの自然言語による説明です。翻訳品質を向上させるため、コンテキストとして送信されます。 ### `runtimeUrl` [#runtime-url] **型** `string | null` · **任意** · **デフォルト** General Translation runtime オンデマンド翻訳に使用する General Translation API のベース URL です。空文字列に設定すると、ランタイム翻訳は完全に無効になります。 ### `cacheUrl` [#cache-url] **型** `string | null` · **省略可能** · **デフォルト** General Translation CDN キャッシュされた翻訳の配信元となるURLです。カスタムのキャッシュホストを指定するか、`null` に設定してリモートでの読み込みを無効にします。 ### `cacheExpiryTime` [#cache-expiry-time] **型** `number` · **任意** · **デフォルト** `60000` ローカルにキャッシュされた翻訳が期限切れになるまでの時間 (ミリ秒) です。このデフォルト値は、開発用キーを使用しない本番環境でのリモート読み込みに適用されます。 ### `loadTranslationsPath` [#load-translations-path] **型** `string` · **任意** [ローカル翻訳](#translations)用のカスタム `loadTranslations` ファイルのパスです。デフォルトでは、プラグインがプロジェクトルートまたは `src/` 内の `loadTranslations.[js|ts]` ファイルを自動的に解決します。 ### `loadDictionaryPath` [#load-dictionary-path] **型** `string` · **省略可能** カスタム `loadDictionary` ファイルへのパス。デフォルトでは、プラグインはプロジェクトルートまたは `src/` 内の `loadDictionary.[js|ts]` ファイルを自動的に見つけて解決します。 ### `dictionary` [#dictionary] **型** `string` · **任意** dictionary ファイルのパスです。プロジェクトルートまたは `src/` にある `dictionary.[js|ts|json]` という名前のファイルは、自動的に検出されます。 ### `config` [#config-path] **型** `string` · **省略可能** · **デフォルト** `./gt.config.json` 読み込む `gt.config.json` ファイルへのパス。 ### `renderSettings` [#render-settings] **型** `{ method: 'skeleton' | 'replace' | 'default'; timeout?: number }` · **任意** ランタイム翻訳の読み込み中に、コンテンツをどのように表示するかを制御します。これは必要時に実行される翻訳にのみ適用され、キャッシュ済みの翻訳はすぐに表示されます。 * `method` — 次のいずれか: * `skeleton` — 待機中は何も表示しません (フラグメント) 。 * `replace` — 待機中はデフォルト言語のコンテンツを表示します。 * `default` — 同じ言語のロケール (`en-US` や `en-GB` など) では `replace` と同様に動作し、異なる言語では `skeleton` と同様に動作します。 * `timeout` — レンダリング方法がタイムアウトして元のコンテンツにフォールバックするまでの時間 (ミリ秒) 。デフォルトは開発環境で `8000`、本番環境で `12000` です。 ```ts title="next.config.ts" export default withGTConfig(nextConfig, { renderSettings: { method: 'skeleton', timeout: 10000, }, }); ``` ### `maxConcurrentRequests` [#max-concurrent-requests] **型** `number` · **任意** · **デフォルト** `100` General Translation API に同時に送信できる翻訳リクエストの最大数。 ### `maxBatchSize` [#max-batch-size] **型** `number` · **任意** · **デフォルト** `25` 1 回のバッチリクエストでまとめて送信できる翻訳の最大数。 ### `batchInterval` [#batch-interval] **型** `number` · **任意** · **デフォルト** `50` リクエスト頻度を制御するため、バッチ処理された翻訳リクエストの間に待機するミリ秒数。 ### `experimentalCompilerOptions` [#compiler-options] **型** `object` · **任意** ビルド時にソースを解析するコンパイラプラグインの設定です。フィールド: | フィールド | 説明 | 型 | デフォルト | | -------------------- | --------------------- | ---------------------------------------------------- | -------- | | `type` | 使用するコンパイラプラグインを指定します。 | `'babel' \| 'swc' \| 'none'` | `'none'` | | `logLevel` | コンパイラのログ出力レベル。 | `'silent' \| 'error' \| 'warn' \| 'info' \| 'debug'` | `'warn'` | | `compileTimeHash` | ビルド時に翻訳ハッシュを事前計算します。 | `boolean` | `true` | | `disableBuildChecks` | ビルド時の検証チェックを無効にします。 | `boolean` | `false` | ### `headersAndCookies` [#headers-and-cookies] **型** `object` · **省略可能** ロケールおよび関連するリクエスト状態を保持するために `gt-next` が使用するheader名とcookie名を上書きします。フィールド: `localeHeaderName`, `localeCookieName`, `enableI18nCookieName`, `referrerLocaleCookieName`, `localeRoutingEnabledCookieName`, `resetLocaleCookieName`。各フィールドの既定値は、libraryの標準名です。 ### リクエスト関数のパス [#request-function-paths] **型** `string` · **任意** `getLocalePath` と `getRegionPath` は、カスタムの `getLocale` および `getRegion` の実装へのパスを指定します。これにより、リクエストのロケールとリージョンの解決方法を上書きできます。 ### `pathRegex` [#path-regex] **Type** `string` · **Optional** JavaScript の正規表現のソース文字列です。設定すると、i18n ミドルウェアとクライアント側のロケールルーティング境界は、それに一致するパス名に対してのみ実行されます。たとえば、`^/(?!uk(?:/|$)).*` を使うと `/uk` 以下をすべてスキップできます。無効な式を指定すると、ビルド時に例外が発生します。これは [`createNextMiddleware`](/docs/react/nextjs/reference/functions/create-next-middleware) ではなく、ここで `withGTConfig` に設定します。プラグインはこれをビルド時にミドルウェアへ転送します。 **ロケールの aliases は手動で処理してください:** フィルタリングされたパスでは、ロケールの正規化は行われません。設定されたロケールが `en`、`en-GB`、`fr` の場合、パスセグメント `uk` は `en-GB` として認識されません。カスタムの `getLocale()` 関数で、`uk` に対して `en-GB` を返す必要があります。 ```ts title="getLocale.ts" import { locale } from 'next/root-params'; export default async function getLocale() { const pathnameLocale = await locale(); if (pathnameLocale === 'uk') return 'en-GB'; return pathnameLocale; } ``` `registerLocale()` を呼び出す前にも、同じ mapping を適用してください。 ```ts registerLocale(locale === 'uk' ? 'en-GB' : locale); ``` `getLocale()` または `registerLocale()` が不明なロケールを受け取ると、`gt-next` は警告を出し、`defaultLocale` にフォールバックします。 ### ESLint オプション [#eslint-options] * `eslint` (`boolean`, default `true`) — セットアップ時に General Translation の ESLint 設定を生成します。 * `eslintSeverity` (`'error' | 'warn'`, default `'warn'`) — 生成されるルールの重大度を指定します。 * `overwriteESLintConfig` (`boolean`, default `false`) — 既存の `eslint.config.mjs` の上書きを許可します。 ルール自体については、[コードの Linting](/docs/react/guides/linting-your-code) を参照してください。 ## ローカル翻訳とCDN翻訳 [#translations] デフォルトでは、`gt-next` は実行時に General Translation CDN から翻訳済みコンテンツを取得します。`npx gt translate` を実行すると、翻訳済みコンテンツは自動的にそこへアップロードされます。必要に応じて、翻訳をアプリにバンドルし、ローカルで読み込むこともできます。 ローカル翻訳は、バンドルサイズが大きくなり、コンテンツを変更するたびに再デプロイが必要になる一方で、読み込みが速く、オフラインでも動作します。これを使うには、ロケールの翻訳を返す `loadTranslations` ファイルを追加します。 ```ts title="src/loadTranslations.ts" export default async function loadTranslations(locale: string) { const translations = await import(`../public/_gt/${locale}.json`); return translations.default; } ``` `withGTConfig` は、プロジェクトルートまたは `src/` ディレクトリ内の `loadTranslations.[js|ts]` ファイルを自動的に検出します (または [`loadTranslationsPath`](#load-translations-path) を明示的に設定できます) 。続いて、`npx gt translate` がその場所にファイルを書き込むよう、CLI が同じディレクトリを参照するように設定してください。ワークフロー全体については、[翻訳をローカルに保存する](/docs/react/guides/storing-translations) を参照してください。 ## 戻り値 [#returns] `withGTConfig` は、General Translation の設定が適用された `NextConfig` オブジェクトを返します。設定が競合している場合、必須の API Key が不足している場合、General Translation のサービスで無効なロケールが使用されている場合、または Production 環境に開発用キーが存在する場合は、ビルド時に例外をスローします。