# General Translation React SDKs (gt-react, gt-next, gt-react-native): 設定
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` とオプションの両方に同じキーが設定されていて値が一致しない場合、ビルド時に競合エラーが発生するため、各値は一か所でのみ管理してください。
* **Pages Router のロケールルーティング。** `nextConfig.i18n` が存在する場合、その `locales` と `defaultLocale` は `gt.config.json` 内で明示的に指定された値と一致している必要があります。不一致の場合、ビルド時に警告が出力されますが、ビルドは停止しません。ロケールの順序は無視され、General Translation の比較では有効なロケールセットに `defaultLocale` が含まれます。Next.js はアクティブなロケールを Pages Router のデータ関数に渡します。
* **認証情報は環境変数から取得されます。** `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                                           | 説明                                                  |
| -------------------------------------------------- | ----------------------------------------------------- |
| `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-`) 。開発時のオンデマンド翻訳に使用します。 |

<Callout type="warn">
  **警告:** 本番用の API キーに `NEXT_PUBLIC_` を絶対に付けないでください。また、開発用キーを本番環境に含めないでください。`NODE_ENV=production` で `GT_DEV_API_KEY` が存在すると、ビルドはエラーになります。
</Callout>

## オプション [#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`](/docs/react/reference/functions/load-translations) ファイルのパス。 | `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`](/docs/react/nextjs/reference/functions/get-region) 関数のパス。 | `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`](/docs/react/reference/functions/load-translations) ファイルのパスです。デフォルトでは、プラグインがプロジェクトルートまたは `src/` 内の `loadTranslations.[js|ts]` ファイルを自動的に解決します。

### `loadDictionaryPath` [#load-dictionary-path]

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

カスタム [`loadDictionary`](/docs/react/reference/functions/load-dictionary) ファイルへのパス。デフォルトでは、プラグインはプロジェクトルートまたは `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`  |
| `enableAutoJsxInjection` | ビルド時に翻訳対象の JSX を自動的にラップします。 | `boolean`                                            | `false`  |

`@generaltranslation/compiler` をインストールしてから、ここで `enableAutoJsxInjection` を設定するか、`gt.config.json` の `files.gt.parsingFlags` で設定してください。CLI の抽出とコンパイラ変換の同期を保つため、`gt.config.json` を優先することをおすすめします。詳しくは [自動 JSX インジェクションの使用](/docs/cli/guides/using-auto-jsx) を参照してください。いずれの場合も、`gt-next` がコンパイラを読み込めるように `type: 'babel'` が必要です:

```ts title="next.config.ts"
export default withGTConfig(nextConfig, {
  experimentalCompilerOptions: {
    type: 'babel',
    enableAutoJsxInjection: true,
  },
});
```

自動 JSX インジェクションは webpack ビルドでのみ実行されます。開発時には `next dev --webpack` を、本番環境では `next build --webpack` を実行してください。Next.js 16 ではデフォルトで Turbopack が使用されます。Turbopack は Babel compiler を無効にするため、`type: 'swc'` または `type: 'none'` ではインジェクションはサポートされません。いずれの場合も、`gt-next` はインジェクションがスキップされたことを警告します。

### `headersAndCookies` [#headers-and-cookies]

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

ロケールおよび関連するリクエスト状態を保持するために `gt-next` が使用するheader名とcookie名を上書きします。フィールド: `localeHeaderName`, `localeCookieName`, `enableI18nCookieName`, `referrerLocaleCookieName`, `localeRoutingEnabledCookieName`, `resetLocaleCookieName`。各フィールドの既定値は、libraryの標準名です。

Next.jsの国際化routingが構成され、`localeDetection` が `false` でない場合、`localeCookieName` がカスタマイズされていても、`gt-next` は標準の `NEXT_LOCALE` 設定cookieを使用します。Next.jsがそのcookieを読み取るのは、自動ロケール検出時のみです。`nextConfig.i18n.localeDetection` を `false` に設定すると、構成されたGeneral Translation cookie名が維持されます。

<Callout type="info">
  **v11.1.3で変更:** Pages Routerのロケール検出がNext.jsの `context.locale` に従うようになり、client-sideでの永続化が `NEXT_LOCALE` と整合するようになりました。カスタムのGeneral Translationロケールcookieを保持するには、`localeDetection: false` を設定してください。
</Callout>

### リクエスト関数のパス [#request-function-paths]

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

`getLocalePath` と `getRegionPath` は、カスタムの [`getLocale`](/docs/react/nextjs/reference/functions/get-locale) および [`getRegion`](/docs/react/nextjs/reference/functions/get-region) の実装へのパスを指定します。これにより、リクエストのロケールとリージョンの解決方法を上書きできます。

### `pathRegex` [#path-regex]

**Type** `string` · **任意**

JavaScript の正規表現のソース文字列です。設定すると、i18n ミドルウェアとクライアント側のロケールルーティング境界は、それに一致するパス名に対してのみ実行されます。たとえば、`^/(?!uk(?:/|$)).*` を使うと `/uk` 以下をすべてスキップできます。無効な式を指定すると、ビルド時に例外が発生します。これは [`createNextMiddleware`](/docs/react/nextjs/reference/functions/create-next-middleware) ではなく、ここで `withGTConfig` に設定します。プラグインはこれをビルド時にミドルウェアへ転送します。

<Callout type="warn">
  **ロケールの aliases は手動で処理してください:** フィルタリングされたパスでは、ロケールの正規化は行われません。設定されたロケールが `en`、`en-GB`、`fr` の場合、パスセグメント `uk` は `en-GB` として認識されません。カスタムの [`getLocale()`](/docs/react/nextjs/reference/functions/get-locale) 関数で、`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()`](/docs/react/nextjs/reference/functions/register-locale) を呼び出す前にも、同じ mapping を適用してください。

  ```ts
  registerLocale(locale === 'uk' ? 'en-GB' : locale);
  ```

  [`getLocale()`](/docs/react/nextjs/reference/functions/get-locale) または [`registerLocale()`](/docs/react/nextjs/reference/functions/register-locale) が不明なロケールを受け取ると、`gt-next` は警告を出し、`defaultLocale` にフォールバックします。
</Callout>

### 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`](/docs/cli/reference/commands/translate) を実行すると、翻訳済みコンテンツは自動的にそこへアップロードされます。必要に応じて、翻訳をアプリにバンドルし、ローカルで読み込むこともできます。

ローカル翻訳は、バンドルサイズが大きくなり、コンテンツを変更するたびに再デプロイが必要になる一方で、読み込みが速く、オフラインでも動作します。これを使うには、ロケールの翻訳を返す [`loadTranslations`](/docs/react/reference/functions/load-translations) ファイルを追加します。

```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`](/docs/cli/reference/commands/translate) がその場所にファイルを書き込むよう、CLI が同じディレクトリを参照するように設定してください。ワークフロー全体については、[翻訳をローカルに保存する](/docs/react/guides/storing-translations) を参照してください。

<Callout type="info">
  **v11.1.0 での変更:** webpack ビルドで、カスタムの [`loadDictionary`](/docs/react/reference/functions/load-dictionary)、[`loadTranslations`](/docs/react/reference/functions/load-translations)、`dictionary` ファイルが正しく解決されるようになりました。ファイルが存在しているにもかかわらず、webpack のすべての辞書参照でエントリが見つからないと報告される場合は、v11.0.x からアップグレードしてください。Turbopack は影響を受けていません。
</Callout>

## 戻り値 [#returns]

`withGTConfig` は、General Translation の設定が適用された `NextConfig` オブジェクトを返します。設定が競合している場合、必須の API Key が不足している場合、General Translation のサービスで無効なロケールが使用されている場合、または Production 環境に開発用キーが存在する場合は、ビルド時に例外をスローします。