# gt-node: General Translation Node.js SDK: 設定
URL: https://generaltranslation.com/ja/docs/node/reference/config.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: initializeGT を使用して General Translation の gt-node ライブラリを設定します。gt-node 設定の API リファレンス。

`gt-node` ライブラリは、起動時に [`initializeGT`](/docs/node/reference/functions/initialize-gt) を 1 回呼び出して設定します。`gt-node` は `gt.config.json` を自動的には読み込みませんが、認証情報についてはフォールバックとして環境変数を使用します。このページでは、その呼び出しで受け付けるキーについて説明します。

## 概要 [#overview]

リクエストを処理する前に、設定オブジェクトを指定して [`initializeGT`](/docs/node/reference/functions/initialize-gt) を一度だけ呼び出します。これは同期的に動作し、戻り値はありません。

```ts
import { initializeGT } from 'gt-node';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr'],
});
```

これらのキーは、[`gt` CLI](/docs/cli/quickstart) が `gt.config.json` から読み込むものに対応しています。両方を同期した状態に保つには、`gt.config.json` をインポートし、そのフィールドを呼び出し時にスプレッドしてください。

```ts
import { initializeGT } from 'gt-node';
import gtConfig from './gt.config.json' with { type: 'json' };

initializeGT(gtConfig);
```

設定の型は `InitializeGTParams` で、ロケール解決オプションと翻訳キャッシュオプションを組み合わせた型です。

## 環境変数 [#env]

[`initializeGT`](/docs/node/reference/functions/initialize-gt) に明示的に渡した値は、環境変数よりも優先されます。

| 変数               | 説明                                   |
| ---------------- | ------------------------------------ |
| `GT_PROJECT_ID`  | `projectId` が省略された場合に使用するプロジェクト ID。  |
| `GT_DEV_API_KEY` | `devApiKey` が省略された場合に使用する開発用 API キー。 |
| `GT_API_KEY`     | `apiKey` が省略された場合に使用する本番用の API キー。   |

## オプション [#options]

| オプション                                        | 説明                                                                                    | 型                                                                     | 任意  | デフォルト                       |
| -------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | --- | --------------------------- |
| [`defaultLocale`](#default-locale)           | ソースおよび代替ロケール。                                                                         | `string`                                                              | Yes | `'en'`                      |
| [`locales`](#locales)                        | サポートされている対象ロケール。                                                                      | `string[]`                                                            | Yes | `[defaultLocale]`           |
| [`projectId`](#project-id)                   | プロジェクト ID。設定すると General Translation CDN ローダーが有効になります。                                 | `string`                                                              | Yes | 設定されている場合は `GT_PROJECT_ID`  |
| [`devApiKey`](#dev-api-key)                  | オンデマンド翻訳用の開発用 API キー。                                                                 | `string`                                                              | Yes | 設定されている場合は `GT_DEV_API_KEY` |
| [`apiKey`](#api-key)                         | 本番用の API キー。                                                                          | `string`                                                              | Yes | 設定されている場合は `GT_API_KEY`     |
| [`cacheUrl`](#cache-url)                     | 翻訳キャッシュのホスト。`null` を指定するとリモート読み込みを無効にします。                                             | `string \| null`                                                      | Yes | GT CDN                      |
| [`runtimeUrl`](#runtime-url)                 | ランタイム翻訳のホスト。`null` を指定すると無効になります。                                                     | `string \| null`                                                      | Yes | GT runtime                  |
| [`loadTranslations`](#load-translations)     | ロケールの翻訳を返すカスタムローダー。                                                                   | `TranslationsLoader`                                                  | Yes | —                           |
| [`customMapping`](#custom-mapping)           | ロケールのエイリアスとプロパティのオーバーライド。                                                             | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Yes | —                           |
| [`cacheExpiryTime`](#cache-expiry)           | ロケールキャッシュの保持期間 (ミリ秒) 。`null` を指定すると有効期限を無効にします。                                       | `number \| null`                                                      | Yes | —                           |
| [`dictionary`](#dictionary)                  | [`getTranslations`](/docs/node/reference/functions/get-translations) で読み取られるソース言語の辞書。 | `Dictionary`                                                          | Yes | —                           |
| [`loadDictionary`](#load-dictionary)         | ロケールの辞書を返すローダー。                                                                       | `DictionaryLoader`                                                    | Yes | —                           |
| [`runtimeTranslation`](#runtime-translation) | ランタイム翻訳の `timeout` と `metadata`。                                                      | `object`                                                              | Yes | `timeout` 12000             |
| [`batchConfig`](#batch-config)               | ランタイム翻訳のバッチ処理の制限。                                                                     | `object`                                                              | Yes | —                           |
| [`modelProvider`](#model-provider)           | `gt.config.json` から引き継がれるモデルプロバイダーキー。ランタイムでは使用されません。                                  | `string`                                                              | Yes | —                           |

*注: [`initializeGT`](/docs/node/reference/functions/initialize-gt) は、内部用のアンダースコア接頭辞付きキー (`_versionId`、`_branchId`、`_disableDevHotReload`) と、CLI コンパイラが使用する `files` オブジェクトも受け取ります。これらは安定した公開仕様の一部ではないため、ここでは省略しています。*

## 環境からの認証情報 [#environment]

設定オブジェクトで認証情報が省略されている場合、[`initializeGT`](/docs/node/reference/functions/initialize-gt) は対応する環境変数を読み取ります。

| オプション       | 環境変数             | 優先順位                       |
| ----------- | ---------------- | -------------------------- |
| `projectId` | `GT_PROJECT_ID`  | 明示的に指定された空でない値が優先され、次に環境変数 |
| `devApiKey` | `GT_DEV_API_KEY` | 明示的に指定された空でない値が優先され、次に環境変数 |
| `apiKey`    | `GT_API_KEY`     | 明示的に指定された空でない値が優先され、次に環境変数 |

明示的に指定された空文字列は未指定として扱われ、環境変数の値にフォールバックします。locales や翻訳ローダーを含むその他の設定フィールドは、環境からは読み取られません。

## `defaultLocale` [#default-locale]

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

アプリケーションのデフォルトロケールです。source コンテンツが記述されているロケールであり、翻訳が見つからない場合のフォールバックロケールでもあります。省略した場合は、ライブラリのデフォルトロケールである `'en'` が使用されます。

```ts
initializeGT({ defaultLocale: 'en-US' });
```

## `locales` [#locales]

**型** `string[]` · **任意** · **デフォルト** `[defaultLocale]`

アプリケーションがサポートする[ロケールコード](/docs/platform/core/reference/utility-functions/locales/is-valid-locale)の配列です。ここで `defaultLocale` を省略しても、サポートされるロケールのセットには常に `defaultLocale` が含まれます。

```ts
initializeGT({ defaultLocale: 'en', locales: ['en', 'es', 'fr', 'ja'] });
```

## `projectId` [#project-id]

**型** `string` · **任意** · **デフォルト** `GT_PROJECT_ID`  (設定されている場合)

General Translation のプロジェクト ID です。General Translation のクラウドサービスを利用する際に必要です。省略した場合は、`GT_PROJECT_ID` にフォールバックします。カスタムの `loadTranslations` を使用せずにこれを設定すると、実行時に翻訳を取得する CDN ローダーが有効になります。

## `devApiKey` [#dev-api-key]

**型** `string` · **任意** · **デフォルト** `GT_DEV_API_KEY` (設定されている場合)

開発用 API キーです。省略した場合は、`GT_DEV_API_KEY` にフォールバックします。`projectId` と組み合わせることで、オンデマンドのランタイム翻訳と開発時のホットリロードが有効になり、[`getGT`](/docs/node/reference/functions/get-gt)、[`getMessages`](/docs/node/reference/functions/get-messages)、[`tx`](/docs/node/reference/functions/tx) が開発中でも新しいコンテンツを翻訳できるようになります。ホットリロードは開発環境でのみ動作します。つまり、`NODE_ENV` が厳密に `'development'` であるか、`import.meta.env.MODE` が `'development'` であるか、`import.meta.env.DEV` が `true` である場合です。`NODE_ENV` が未設定の場合を含め、その他の値はすべて本番環境として扱われるため、ホットリロードには `NODE_ENV=development` を設定してください。

## `apiKey` [#api-key]

**型** `string` · **任意** · **デフォルト** `GT_API_KEY`  (設定されている場合)

本番用の API キーです。省略した場合は、`GT_API_KEY` にフォールバックします。本番環境でランタイム翻訳が必要な場合に設定します。ほとんどのデプロイでは、代わりに [`gt` CLI](/docs/cli/quickstart) を使って事前に翻訳を生成します。

## `cacheUrl` [#cache-url]

**型** `string | null` · **任意** · **デフォルト** GT CDN

翻訳キャッシュサービスのURLです。独自のCDNから翻訳を読み込む場合はカスタムホストを設定し、リモートキャッシュの読み込みを無効にする場合は `null` を設定します。

## `runtimeUrl` [#runtime-url]

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

[`tx`](/docs/node/reference/functions/tx) とオンデマンドの開発時の翻訳で使用される、ランタイム翻訳サービスの URL です。`null` または `''` に設定すると、ランタイム翻訳を無効にできます。

## `loadTranslations` [#load-translations]

**型** `TranslationsLoader` · **任意**

General Translation CDN の代わりに、独自のソースから翻訳を読み込むカスタム関数です。ロケールコードを受け取り、そのロケールの翻訳を返します。

```ts
type TranslationsLoader = (locale: string) => Promise<unknown>;
```

```ts
initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es'],
  loadTranslations: async (locale) => {
    const res = await fetch(`https://my-api.com/translations/${locale}`);
    return res.json();
  },
});
```

## `customMapping` [#custom-mapping]

**型** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **任意**

カスタムロケールコードを標準ロケールコードまたは [locale property](/docs/node/reference/functions/get-locale-properties) の上書きに対応付けるためのマッピングです。コードのエイリアス (たとえば `cn` を `zh` に) を設定したり、表示プロパティを上書きしたりする際に使用します。

## `cacheExpiryTime` [#cache-expiry]

**型** `number | null` · **任意**

ロケールキャッシュの保持期間 (ミリ秒) 。デフォルトの TTL を使う場合は `undefined` のままにし、明示的に TTL を指定する場合は数値を設定し、有効期限を無効にする場合は `null` を設定します。

## `dictionary` [#dictionary]

**型** `Dictionary` · **任意**

ソース言語の翻訳エントリを、`id` をキーとして格納した辞書です。エントリは各リクエストで [`getTranslations`](/docs/node/reference/functions/get-translations) によって解決されます。

## `loadDictionary` [#load-dictionary]

**型** `DictionaryLoader` · **任意**

指定したロケールの辞書を返すローダーです:

```ts
type DictionaryLoader = (locale: string) => Promise<Dictionary>;
```

## `runtimeTranslation` [#runtime-translation]

**Type** `object` · **任意** · **デフォルト** `timeout` 12000 ms

[`tx`](/docs/node/reference/functions/tx) と on-demand な開発時の翻訳に適用されるランタイム翻訳の設定です。

* `timeout?: number` — ミリ秒単位のリクエストタイムアウト (デフォルトは `12000`) 。
* `metadata?: object` — すべてのランタイム翻訳リクエストにマージされるメタデータです。`modelProvider` (下記の [`modelProvider`](#model-provider) を参照) や `sourceLocale` など、ランタイム専用の翻訳ヒントはここに指定します。

## `batchConfig` [#batch-config]

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

[`tx`](/docs/node/reference/functions/tx) とオンデマンドの開発時の翻訳で、ランタイム翻訳リクエストをどのようにバッチ処理するかを制御します。デフォルト設定を使用する場合は、未定義のままにしてください。

* `maxConcurrentRequests?: number` — 同時に処理中のバッチリクエストの最大数。
* `maxBatchSize?: number` — 1 回のバッチリクエストあたりのエントリの最大数。
* `batchInterval?: number` — バッチが送信されるまでの遅延時間 (ミリ秒) 。

## `modelProvider` [#model-provider]

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

`gt.config.json` の `modelProvider` キーを反映したもので、[`gt` CLI](/docs/cli/quickstart) はこれを使って翻訳モデルを選択します。`gt-node` ランタイムはこのトップレベルのキーを**参照しません**。これは、`gt.config.json` をスプレッドしてもエラーにならないよう受け付けているだけです。ランタイム翻訳 ([`tx`](/docs/node/reference/functions/tx)) で使用するモデルを選択するには、代わりに [`runtimeTranslation`](#runtime-translation) の `metadata` 内で `modelProvider` を設定してください。

## 例 [#example]

```ts title="server.js"
import { initializeGT } from 'gt-node';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr', 'ja'],
  // 認証情報は GT_PROJECT_ID、GT_API_KEY、GT_DEV_API_KEY から読み込まれます。
});
```

## Sitemap

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