# gt-node: General Translation Node.js SDK: 設定
URL: https://generaltranslation.com/ja/docs/node/reference/config.mdx
---

title: 設定
description: initializeGT を使用して General Translation の gt-node ライブラリを設定します。gt-node 設定の API リファレンス。

---

`gt-node` ライブラリは、起動時に [`initializeGT`](/docs/node/reference/functions/initialize-gt) を 1 回呼び出して設定します。`gt-node` は `gt.config.json` や環境変数を自動的には読み込まず、すべての値は `initializeGT` に渡すオブジェクトから取得されます。このページでは、その呼び出しで受け付けるキーについて説明します。

## 概要 [#overview]

リクエストを処理する前に、設定オブジェクトを指定して `initializeGT` を一度だけ呼び出します。これは同期的に動作し、戻り値はありません。

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

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr'],
  projectId: process.env.GT_PROJECT_ID,
});
```

これらのキーは、[`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` で、ロケール解決オプションと翻訳キャッシュオプションを組み合わせた型です。

## オプション [#options]

| オプション                                        | 説明                                                                                    | 型                                                                     | 任意  | デフォルト             |
| -------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | --- | ----------------- |
| [`defaultLocale`](#default-locale)           | ソースおよびフォールバックのロケール。                                                                   | `string`                                                              | Yes | `'en'`            |
| [`locales`](#locales)                        | サポートされている対象ロケール。                                                                      | `string[]`                                                            | Yes | `[defaultLocale]` |
| [`projectId`](#project-id)                   | プロジェクト ID。設定すると General Translation CDN ローダーが有効になります。                                 | `string`                                                              | Yes | —                 |
| [`devApiKey`](#dev-api-key)                  | オンデマンド翻訳用の開発用 API キー。                                                                 | `string`                                                              | Yes | —                 |
| [`apiKey`](#api-key)                         | 本番用の API キー。                                                                          | `string`                                                              | Yes | —                 |
| [`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` は、内部用のアンダースコア接頭辞付きキー (`_versionId`、`_branchId`、`_disableDevHotReload`) と、CLI コンパイラが使用する `files` オブジェクトも受け取ります。これらは安定した公開仕様の一部ではないため、ここでは省略しています。*

## `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` · **任意**

General Translation の project ID です。General Translation のクラウドサービスを利用する際に必要です。これを設定すると (カスタムの `loadTranslations` を使用しない場合) 、実行時に翻訳を取得する CDN ローダーが有効になります。

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

**型** `string` · **省略可能**

開発用 API キーです。`projectId` と組み合わせることで、オンデマンドの実行時翻訳と開発時のホットリロードが有効になり、[`getGT`](/docs/node/reference/functions/get-gt)、[`getMessages`](/docs/node/reference/functions/get-messages)、[`tx`](/docs/node/reference/functions/tx) が開発中でも新しいコンテンツを翻訳できるようになります。ホットリロードは、`NODE_ENV` が `'production'` ではない場合にのみ動作します。

## `apiKey` [#api-key]

**型** `string` · **省略可能**

本番用の API キーです。本番環境でランタイム翻訳が必要な場合に設定します。ほとんどのデプロイでは、代わりに [`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` · **任意**

カスタムロケールコードを標準ロケールコードまたは [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'],
  projectId: process.env.GT_PROJECT_ID,
});
```