# gt: General Translation CLI tool: 設定
URL: https://generaltranslation.com/ja/docs/cli/reference/config.mdx
---
title: 設定
description: gt.config.json ファイルの設定に関するドキュメント
---

## 概要

`gt.config.json` ファイルは、プロジェクトの GT 設定を構成するために使用します。プロジェクトのルートに配置してください。

CLI のセットアップウィザード [`npx gt init`](/docs/cli/init) を使うと、プロジェクト内に `gt.config.json` ファイルが作成されます。

## 設定

`gt.config.json` ファイルでは、以下を含むプロパティを指定できます。

* `defaultLocale`: プロジェクトのデフォルトのロケールです。ソースコンテンツが記述されるロケールを指します。また、プロジェクトのフォールバックロケールでもあります (`gt-next` または `gt-react` を使用している場合) 。

* `locales`: プロジェクトのロケール配列です。プロジェクトの翻訳先にしたいロケールを指定します。詳しくは [対応ロケール](/docs/platform/supported-locales) を参照してください。
  `gt-next` または `gt-react` を使用している場合、これらはアプリがサポートするロケールでもあります。

* `files`: 翻訳したいコンテンツに関する情報を含むオブジェクトです。

* `publish`: 任意のブールフラグです。`true` の場合、`translate`、`upload`、または `save-local` の実行後に、翻訳済みファイルが GT CDN に公開されます。デフォルトは `false` (公開しない) です。`--publish` を使ってコマンドごとに設定することもできます。詳しくは [CDN 公開](#cdn-publishing) を参照してください。

* `stageTranslations`: プロジェクトが人手によるレビューを使用するよう設定されているかどうかを示す、任意のブールフラグです。

* `src`: ソースファイル用のファイル glob パターンを指定する任意の配列です。デフォルトでは、次のように設定されています。

```json
[
  "src/**/*.{js,jsx,ts,tsx}",
  "app/**/*.{js,jsx,ts,tsx}",
  "pages/**/*.{js,jsx,ts,tsx}",
  "components/**/*.{js,jsx,ts,tsx}"
]
```

* `dictionary`: 辞書ファイルへの相対パスを指定する、省略可能な文字列です。

* `branchOptions`: branch ベースの翻訳トラッキングを設定するための省略可能なオブジェクトです。詳しくは [branching](/docs/cli/branching) を参照してください。

<Callout type="info">
  `gt.config.json` ファイルの検証に役立てるため、CLI 用の [JSON Schema](https://assets.gtx.dev/config-schema.json) を利用できます。

  `gt.config.json` ファイルの先頭に次を追加してください。

  ```json title="gt.config.json" copy
  {
    "$schema": "https://assets.gtx.dev/config-schema.json"
  }
  ```
</Callout>

以下は `gt.config.json` ファイルのひな形です。

```json title="gt.config.json"
{
  "$schema": "https://assets.gtx.dev/config-schema.json",
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "..."
    },
    "json": {
      "include": [...]
    },
    "mdx": {
      "include": [...]
    },
    "md": {
      "include": [...]
    }
  },
  "src": [
    "src/**/*.{ts,tsx}",
  ],
  "dictionary": "./dictionary.json"
}
```


### ロケールのエイリアス

ロケールにエイリアスを設定する場合 (例: `zh` ではなく `cn` を使う場合) は、`gt.config.json` ファイルでカスタムマッピングを指定できます。

```json title="gt.config.json"
{
  "customMapping": {
    // エイリアスロケール
    "cn": {
      "code": "zh" // 公式のBCP 47ロケールコード
    }
  }
}
```

エイリアスしたロケールに対して、別の属性を指定することもできます。

```json title="gt.config.json"
{
  "customMapping": {
    "cn": {
      "code": "zh",
      "name": "Mandarin"
    }
  }
}
```


### ブランチオプション

設定ファイルでブランチの設定を行う場合は、`branchOptions` オブジェクトを使用できます。

```json title="gt.config.json"
{
  "branchOptions": {
    "enabled": true,
    "currentBranch": "my-feature-branch",
    "autoDetectBranches": true,
    "remoteName": "origin"
  }
}
```

| プロパティ                | 説明                                        | デフォルト       |
| -------------------- | ----------------------------------------- | ----------- |
| `enabled`            | プロジェクトで ブランチ を有効にする                     | `false`     |
| `currentBranch`      | 現在の ブランチ 名を上書きします (自動検出の代わり)            | `undefined` |
| `autoDetectBranches` | ブランチ 関係 (流入元とチェックアウト中の ブランチ) を自動検出します | `true`      |
| `remoteName`         | ブランチ の検出に使用する Git リモート名                 | `"origin"`  |

<Callout type="info">
  CLI フラグは設定ファイルのオプションより優先されます。詳しくは [branching ガイド](/docs/cli/branching) を参照してください。
</Callout>

***


## `files`

### サポートされるファイルタイプ

`files` には、翻訳対象にしたい各ファイルタイプごとにキーを指定する必要があります。
プロジェクトでは複数のファイルタイプを組み合わせて設定でき、それらをまとめて翻訳できます。
現在サポートしているファイルタイプは次のとおりです。

* `gt`: General Translation ファイル。[`gt-next`](/docs/next)、[`gt-react`](/docs/react)、[`gt-react-native`](/docs/react-native) で使用されます。
* `json`: JSON ファイル。
* `pot`: PO/POT (gettext) ファイル。
* `yaml`: YAML ファイル。
* `mdx`: Markdown コンポーネント (MDX) ファイル。
* `md`: Markdown (MD) ファイル。
* `js`: JavaScript ファイル。
* `ts`: TypeScript ファイル。
* `html`: HTML ファイル。
* `txt`: テキスト ファイル。
* `twilioContentJson`: Twilio Content JSON ファイル。[Twilio Content Templates](https://www.twilio.com/docs/content) の翻訳に使用されます。

各ファイルタイプには、次のキーを1つ以上含むオブジェクトを対応させる必要があります。

* `include`
* `exclude`
* `transform`
* `transformationFormat`
* `output`

### `include`

使用する場合、`include` キーの値には、翻訳対象のファイルに一致するグロブパターンの配列を指定する必要があります。

ソースファイルを正しく検出し、翻訳済みファイルを正しい場所に保存するために、グロブパターンでは `[locale]` プレースホルダーを必ず使用してください。
CLI ツールは、翻訳対象ファイルを検索する際、`[locale]` プレースホルダーを `defaultLocale` の値に置き換えます。

CLI ツールは、`[locale]` プレースホルダーを対象のロケールコードに置き換えた対応するパスに、翻訳済みファイルを保存します。

```json
{
  "include": ["docs/[locale]/**/*.json"]
}
```


### `exclude`

指定する場合、`exclude` キーの値は、翻訳対象から除外するファイルに一致する グロブパターン の配列である必要があります。

このパターンは `include` パターンと同じですが、`[locale]` プレースホルダーを省略できる点だけが異なります。指定した場合は、`defaultLocale` の値に置き換えられます。

```json
{
  "exclude": ["docs/[locale]/exclude/**/*.json"]
}
```

すべてのロケールでファイルを翻訳対象から除外するには、`[locale]` の代わりに `[locales]` プレースホルダーを使用できます。

```json
{
  "exclude": ["docs/[locales]/exclude/**/*.json"]
}
```

### `transform`

`transform` には、文字列またはオブジェクトを指定できます。

`transform` が文字列の場合、ファイル名のリマッピングを定義します。ここにはワイルドカード `*` を含める必要があり、これは元のファイル名 (最初の `.` より前の部分) に置き換えられます。

たとえば、翻訳済みファイルの拡張子をすべて `.json` ではなく `.[locale].json` にしたい場合は、次の設定を使用できます。

```json
{
  "transform": "*.[locale].json"
}
```

また、`transform` がオブジェクトの場合は、次のプロパティを含める必要があります。

* `match` (省略可) : 文字列にマッチさせるための正規表現パターン。キャプチャグループをサポートします
* `replace` (必須) : マッチした部分を置き換える文字列または正規表現パターン

どちらの値でも正規表現のキャプチャグループを使用でき、出力ファイルの完全な相対ファイル名に対して適用されます。

```json
{
  "transform": {
    "match": "^(.*)$",
    "replace": "{locale}/$1"
  }
}
```

たとえば、上記の設定では、翻訳済みファイルが対象ロケールのサブディレクトリ以下に保存されます。


#### 特殊なプレースホルダー

`transform` オプションでは、`match` 文字列と `replace` 文字列の両方で使える、いくつかの特殊なプレースホルダーをサポートしています。

* `{locale}`: コンテキストに応じて動作が変わるロケールコードのプレースホルダー
  * **`match` 文字列内**: ソースファイルを特定しやすくするため、デフォルトのロケールコード (例: `"en"`) に置き換えられます
  * **`replace` 文字列内**: 翻訳後の出力ファイル向けに、対象ロケールのコード (例: `"fr"`、`"es"`) に置き換えられます

たとえば、デフォルトのロケールが `"en"` で、`"fr"` に翻訳する場合:

* `match` パターン `"content/{locale}/file.md"` は `"content/en/file.md"` になります
* `replace` パターン `"content/{locale}/file.md"` は `"content/fr/file.md"` になります

さらに、`getLocaleProperties` のその他のプロパティも、同じようにコンテキストに応じて動作するプレースホルダーとして使用できます。

<Callout type="info">
  これは、ドキュメントや i18n フレームワークで、サブディレクトリベースのロケールルーティングではなく、翻訳済みファイルに特定のファイル拡張子が必要な場合に便利です。
</Callout>

### `transformationFormat`

`transformationFormat` キーは、翻訳後に出力されるファイルに別のファイル形式を指定します。これは、ソースファイルが template であり、翻訳後に異なるファイルタイプを出力する必要がある場合に便利です。

たとえば、POT (PO Template) ファイルはソース template ですが、翻訳後の出力は PO ファイルにする必要があります。

```json
{
  "files": {
    "pot": {
      "include": ["locales/[locale]/**/*.pot"],
      "transformationFormat": "PO"
    }
  }
}
```

値には、対応しているファイル形式キーのいずれかに一致する文字列 (例: `"PO"`) を指定する必要があります。

### `output`

このキーは General Translation のファイルでのみ使用し、特に翻訳をローカルに保存するために使います。GT CDN を使用する場合、このキーは不要です。

値には、翻訳の保存先を示す `[locale]` プレースホルダーを含む文字列を指定します。

たとえば、スペイン語の翻訳を `public/i18n` ディレクトリ内の `ui.es.json` というファイルに保存する場合は、次の文字列を使用します。

```json
{
  "output": "public/i18n/[locale].json"
}
```

<Callout type="info">
  このオプションは、`gt-next` または `gt-react` を使用し、GT CDN ではなく翻訳をローカルに保存したい場合にのみ使用してください。

  現時点では、生成できるファイルは各ロケールにつき 1 つだけです。
</Callout>

***


### ファイルタイプ: `gt` [#gt]

**サポートされるキー**

* `output` (必須) 

**例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json"
    }
  }
}
```

この設定を行うと、CLI ツールはフランス語とスペイン語の翻訳を `public/i18n/[locale].json` ディレクトリに保存します。

デフォルトでは、この設定を使用しても、CLI ツールは翻訳を GT CDN に公開しません。

***


### ファイルタイプ: `json` [#json]

**サポートされるキー**

* `include` (必須) 
* `exclude` (任意) 
* `transform` (任意) 

**例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "json": {
      "include": ["json_files/[locale]/**/*.json"],
      "exclude": ["json_files/[locale]/exclude/**/*.json"]
    }
  }
}
```

プロジェクトのデフォルトのロケールが `en` で、`fr` と `es` に翻訳したいとします。

この設定では、CLI はサブディレクトリ `json_files/en/` 配下にあるすべての JSON ファイルを検索し、翻訳後のファイルを `json_files/fr/` と `json_files/es/` に保存します。

`json_files/en/exclude/` サブディレクトリ内のファイルはすべて無視されます。

***


### ファイルタイプ: `yaml` [#yaml]

**サポートされるキー**

* `include` (必須) 
* `exclude` (任意) 
* `transform` (任意) 

**例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "yaml": {
      "include": ["yaml_files/[locale]/**/*.yaml"],
      "exclude": ["yaml_files/[locale]/exclude/**/*.yaml"]
    }
  }
}
```

プロジェクトのデフォルトのロケールが `en` で、`fr` と `es` に翻訳したいとします。

この設定では、CLI はサブディレクトリ `yaml_files/en/` 配下にあるすべての YAML ファイルを検索し、翻訳済みのファイルを `yaml_files/fr/` と `yaml_files/es/` に保存します。

サブディレクトリ `yaml_files/en/exclude/` 内のファイルは無視します。

***


### ファイルタイプ: `mdx` [#mdx]

**サポートされるキー**

* `include` (必須) 
* `exclude` (任意) 
* `transform` (任意) 

**例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "mdx": {
      "include": ["content/docs/[locale]/**/*.mdx"],
      "transform": "*.[locale].mdx"
    }
  }
}
```

この設定により、CLI ツールは `content/docs/en` ディレクトリ配下にあるすべての MDX ファイルを検索し、翻訳済みファイルを `content/docs/ja` ディレクトリに保存します。

`transform` キーを指定すると、翻訳済みファイルの拡張子が `.ja.mdx` に変更されます。

***


### ファイルタイプ: `md` [#md]

**サポートされるキー**

* `include` (必須) 
* `exclude` (任意) 
* `transform` (任意) 

**例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "md": {
      "include": ["content/docs/[locale]/**/*.md"],
      "exclude": ["content/docs/[locale]/exclude/**/*.md"],
      "transform": "*.[locale].md"
    }
  }
}
```

この設定により、CLI ツールは `content/docs/en` ディレクトリ配下にあるすべての MD ファイルを検索し、翻訳後のファイルを `content/docs/ja` ディレクトリに保存します。

`transform` キーを指定すると、翻訳後のファイルの拡張子は `.ja.md` に変更されます。

`content/docs/en/exclude` ディレクトリ内のすべてのファイルは無視されます。

***


### ファイルタイプ: `js` [#js]

**サポートされるキー**

* `include` (必須) 
* `exclude` (任意) 
* `transform` (任意) 

**例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "js": {
      "include": ["scripts/[locale]/**/*.js"]
    }
  }
}
```

この設定により、CLI ツールは `scripts/en` ディレクトリ配下のすべての JavaScript ファイルを探し、翻訳したファイルを `scripts/fr` と `scripts/es` ディレクトリに保存します。

***


### ファイルタイプ: `ts` [#ts]

**サポートされるキー**

* `include` (必須) 
* `exclude` (任意) 
* `transform` (任意) 

**例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "ts": {
      "include": ["scripts/[locale]/**/*.ts"]
    }
  }
}
```

この設定を行うと、CLI ツールは `scripts/en` ディレクトリ配下にあるすべての TypeScript ファイルを検索し、翻訳後のファイルを `scripts/fr` ディレクトリおよび `scripts/es` ディレクトリに保存します。

***


### ファイルタイプ: `html` [#html]

**サポートされるキー**

* `include` (必須)
* `exclude` (任意)
* `transform` (任意)

**例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "html": {
      "include": ["content/docs/[locale]/**/*.html"],
      "exclude": ["content/docs/[locale]/exclude/**/*.html"],
      "transform": "*.[locale].html"
    }
  }
}
```

この設定により、CLI ツールは `content/docs/en` ディレクトリ配下にあるすべての HTML ファイルを探し、翻訳後のファイルを `content/docs/ja` ディレクトリに保存します。

`transform` キーによって、翻訳後のファイルの拡張子は `.ja.html` に変更されます。

`content/docs/en/exclude` ディレクトリ内のすべてのファイルは無視されます。

***


### ファイルタイプ: `txt` [#txt]

**サポートされるキー**

* `include` (必須)
* `exclude` (任意)
* `transform` (任意)

**例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "txt": {
      "include": ["content/docs/[locale]/**/*.txt"],
      "exclude": ["content/docs/[locale]/exclude/**/*.txt"],
      "transform": "*.[locale].txt"
    }
  }
}
```

この設定により、CLI ツールは `content/docs/en` ディレクトリ配下にあるすべてのテキストファイルを検索し、翻訳済みファイルを `content/docs/ja` ディレクトリに保存します。

`transform` キーを指定すると、翻訳済みファイルの拡張子は `.ja.txt` に変更されます。

`content/docs/en/exclude` ディレクトリ内のすべてのファイルは無視されます。

***


### ファイルタイプ: `twilioContentJson` [#twilioContentJson]

**サポートされるキー**

* `include` (必須) 
* `exclude` (任意) 
* `transform` (任意) 

**例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "twilioContentJson": {
      "include": ["twilio/[locale]/**/*.json"]
    }
  }
}
```

この設定により、CLI ツールは `twilio/en` ディレクトリ配下にあるすべての Twilio Content JSON ファイルを検索し、翻訳後のファイルを `twilio/es` および `twilio/fr` ディレクトリに保存します。

Twilio Content JSON ファイルは、WhatsApp、SMS、RCS メッセージ向けに [Twilio&#39;s Content Template Builder](https://www.twilio.com/docs/content) で使用される構造化された template です。CLI は、template の構造、変数のプレースホルダー、翻訳不要なフィールドを維持したまま、ユーザー向けの文字列値 (本文テキスト、ボタンラベル、カードタイトル) を翻訳します。

***


## CDN への公開 [#cdn-publishing]

デフォルトでは、CLI は翻訳済みファイルを GT CDN に公開しません。プロジェクト設定で CDN を有効にしている場合は、公開をグローバル単位、ファイル単位、またはコマンド単位で制御できます。

### グローバル公開フラグ

トップレベルで `publish` を設定すると、翻訳済みの**すべての**ファイルが CDN に公開されます。

```json title="gt.config.json"
{
  "publish": true
}
```

`translate`、`upload`、または `save-local` コマンドに `--publish` を指定することもできます。

```bash
npx gt translate --publish
```


### GT JSON 公開フラグ

GT の内部翻訳形式のみを公開するには、`files.gt` 配下の `publish` キーを使用します:

```json title="gt.config.json"
{
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json",
      "publish": true
    }
  }
}
```


### ファイルごとの公開制御

その他のファイル形式 (`json`、`yaml`、`mdx`、`md`、`po`、`xliff`、`csv`、`properties`) では、単純なグロブ文字列の代わりに `include` 配列内でオブジェクトを指定することで、ファイルごとに公開を制御できます。

```json title="gt.config.json"
{
  "files": {
    "json": {
      "include": [
        { "pattern": "locales/[locale]/*.json", "publish": true },
        { "pattern": "locales/[locale]/internal/**/*.json", "publish": false }
      ]
    }
  }
}
```

`include` 内の各エントリは、次のいずれかです。

* **文字列** — グロブパターン (公開設定は指定されず、グローバルの `publish` 設定が使用されます) 
* `pattern` (グロブパターン) と `publish` (boolean) を持つ**オブジェクト** — 一致したファイルを公開対象に含めるか除外するかを明示的に指定します


### 解決順序

各ファイルについて、CLIは公開するかどうかを次の順序で判定します。

1. **明示的なオプトアウト** — ファイルが `"publish": false` を持つ include エントリに一致する → 公開されないか、CDN から削除される
2. **明示的なオプトイン** — ファイルが `"publish": true` を持つ include エントリに一致する → CDN に公開される
3. **グローバルなフォールバック** — 最上位レベルの `publish` 設定を使用する (未設定の場合のデフォルトは `false`) 

どのレベルにも `publish` 設定が存在しない場合、公開ステップは完全にスキップされます。

***

## 設定例

では、`gt.config.json` の設定例を見ていきましょう。

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json"
    },
    "mdx": {
      "include": ["content/docs/[locale]/**/*.mdx"],
      "transform": "*.[locale].mdx"
    },
    "json": {
      "include": ["resources/[locale]/**/*.json"],
      "exclude": ["resources/[locale]/exclude/**/*.json"]
    }
  }
}
```

この例では、[`gt translate`](/docs/cli/translate) を1回実行するだけで、次のファイルを翻訳できます。

* `content/docs/en` ディレクトリ内のすべての MDX ファイル。
* `resources/en` ディレクトリ内のすべての JSON ファイル (`resources/en/exclude` ディレクトリ内のファイルを除く) 。
* React または Next.js プロジェクト内のすべてのインライン `<T>` コンポーネント。
* `dictionary.[json|js|ts]` ファイル。

GT: 翻訳は `public/i18n/es.json` と `public/i18n/fr.json` に保存されます。これらのファイルは [`loadTranslations`](/docs/react/api/config/load-translations) を使って読み込めます。

MDX: 翻訳は `content/docs/fr` ディレクトリと `content/docs/es` ディレクトリに保存されます。
ファイル拡張子は、それぞれ `.mdx` から `.fr.mdx` と `.es.mdx` に変更されます。

JSON: 翻訳は `resources/fr` ディレクトリと `resources/es` ディレクトリに保存されます。

***


## 次のステップ

[init コマンド](/docs/cli/init) を使ってこの設定ファイルを生成する方法を確認してください。