# gt: General Translation CLI tool: 設定
URL: https://generaltranslation.com/ja/docs/cli/reference/config.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: `gt.config.json` ファイルで General Translation CLI を設定します。`gt.config.json` の API リファレンス。
`gt.config.json` ファイルでは、CLI が翻訳する対象と、結果の保存先を設定します。プロジェクトのルートに配置してください。[`gt init`](/docs/cli/reference/commands/init) または [`gt configure`](/docs/cli/reference/commands/configure) で作成するか、手動で記述できます。
*注: エディタでの検証と自動補完のために、`$schema` キーで [JSON Schema](https://assets.gtx.dev/config-schema.json) を追加してください。公開されているスキーマは、`pot`、`html`、`txt`、`twilioContentJson`、`lottie`、`dotStrings`、`dotStringsdict`、`androidStrings`、`xcstrings`、`srt` をはじめとする一部の有効なファイルキーに追随できておらず、`fonts` および `options.saveLocal` も含まれていません。スキーマが更新されるまで、エディタでスキーマ未対応のフィールドにフラグが付く場合があります。*
## オプション [#options]
| オプション | 説明 | 型 | 任意 | デフォルト |
| ------------------------------------ | ---------------------------------------- | ---------- | -- | --------------------- |
| [`projectId`](#project-id) | API および翻訳ワークフローで使用するプロジェクト。 | `string` | はい | `GT_PROJECT_ID` |
| [`baseUrl`](#base-url) | General Translation API リクエストのベース URL。 | `string` | はい | `https://api.gtx.dev` |
| [`defaultLocale`](#default-locale) | ソースコンテンツが記述されているロケール。 | `string` | はい | `en` |
| [`locales`](#locales) | 翻訳先のターゲットロケール。 | `string[]` | はい | — |
| [`files`](#files) | 翻訳するファイルと保存先。 | `object` | はい | — |
| [`fonts`](#fonts) | Lottie 翻訳ジョブで利用可能にするフォントファイル。 | `object` | はい | — |
| [`publish`](#publish) | 翻訳済みファイルを CDN に公開します。 | `boolean` | はい | `false` |
| [`stageTranslations`](#stage) | 翻訳をダウンロードする前にステージングワークフローを使用します。 | `boolean` | はい | `false` |
| [`requiresReview`](#requires-review) | すべての翻訳済みファイルに適用されるデフォルトのレビュー必須設定ポリシー。 | `boolean` | はい | `false` |
| [`src`](#src) | インラインコンテンツを検出するために走査するソースファイルのglob パターン。 | `string[]` | はい | フレームワークごとに異なる |
| [`dictionary`](#dictionary) | dictionary ファイルへのパス。 | `string` | はい | — |
| [`branchOptions`](#branch-options) | ブランチごとの翻訳追跡設定。 | `object` | はい | — |
| [`customMapping`](#custom-mapping) | ロケールのエイリアスとプロパティのオーバーライド。 | `object` | はい | — |
| [`options.saveLocal`](#save-local) | エンキュー前にローカルの翻訳編集を検出して送信します。 | `boolean` | はい | `false` |
## `projectId` [#project-id]
**型** `string` · **任意** · **デフォルト** `GT_PROJECT_ID`
API および翻訳ワークフローで使用するプロジェクトです。`--project-id` フラグは環境変数の値を上書きしますが、config に `projectId` が指定されている場合は、その値と一致している必要があります。
```json title="gt.config.json"
{
"projectId": "project-id"
}
```
## `baseUrl` [#base-url]
**型** `string` · **任意** · **デフォルト** `https://api.gtx.dev`
[`gt api`](/docs/cli/reference/commands/api) を含む CLI のリクエストで使用される API のオリジンです。カスタムの General Translation API エンドポイントを使用するワークフローの場合にのみ設定してください。
```json title="gt.config.json"
{
"baseUrl": "https://api.gtx.dev"
}
```
## `defaultLocale` [#default-locale]
**型** `string` · **任意** · **デフォルト** `en`
ソースコンテンツが記述されているロケールです。CLI はこのロケールを翻訳元として使用し、`gt-next`、`gt-react`、`gt-vue` を使用する場合のフォールバック ロケールにもなります。
```json title="gt.config.json"
{
"defaultLocale": "en"
}
```
## `locales` [#locales]
**型** `string[]` · **任意** · **デフォルト** —
翻訳先のターゲットロケールを指定します。使用可能なコードについては、[サポートされているロケール](/docs/platform/dashboard/reference/supported-locales)を参照してください。ロケールのリストを受け取るフレームワークのイニシャライザでは、これらがアプリのサポートするロケールとしても使用されます。
```json title="gt.config.json"
{
"locales": ["fr", "es", "ja"]
}
```
## `files` [#files]
**型** `object` · **任意** · **デフォルト** —
翻訳対象のファイル形式ごとに 1 つのキーを持つオブジェクトです。各形式は設定オブジェクトに対応します。形式ごとの詳細については、[ファイル形式](/docs/cli/reference/formats/gt-jsx-files) を参照してください。
### サポートされているファイルタイプ
| キー | ファイルタイプ | 参照 |
| ------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| `gt` | `gt-next`、`gt-react`、`gt-react-native`、`gt-tanstack-start`、`gt-vue` 用の General Translation ファイル。 | [GT](/docs/cli/reference/formats/gt-jsx-files) |
| `json` | JSON ファイル。 | [JSON](/docs/cli/reference/formats/json-files) |
| `yaml` | YAML ファイル (`.yaml` および `.yml`) 。 | [YAML](/docs/cli/reference/formats/yaml-files) |
| `pot` | PO/POT gettext ファイル。 | [PO / POT](/docs/cli/reference/formats/po-pot-files) |
| `mdx` | MDX ファイル。 | [MDX and Markdown](/docs/cli/reference/formats/mdx-md-files) |
| `md` | Markdown ファイル。 | [MDX and Markdown](/docs/cli/reference/formats/mdx-md-files) |
| `ts` | TypeScript ファイル。 | [TypeScript and JavaScript](/docs/cli/reference/formats/ts-js-files) |
| `js` | JavaScript ファイル。 | [TypeScript and JavaScript](/docs/cli/reference/formats/ts-js-files) |
| `html` | HTML ファイル。 | [HTML](/docs/cli/reference/formats/html-files) |
| `txt` | プレーンテキスト ファイル。 | [Plain text](/docs/cli/reference/formats/plain-text-files) |
| `srt` | SubRip 字幕ファイル (`.srt`)。 | [SRT](/docs/cli/reference/formats/srt-files) |
| `twilioContentJson` | Twilio Content JSON テンプレート。 | — |
| `lottie` | dotLottie アニメーションファイル (`.lottie`)。 | [Lottie](/docs/cli/reference/formats/lottie-files) |
| `xcstrings` | Apple String Catalogs (`.xcstrings`)。 | [.xcstrings](/docs/cli/reference/formats/xcstrings-files) |
| `dotStrings` | `.strings` テーブル。`.lproj` ディレクトリ内にロケールごとに 1 つ。 | [.strings](/docs/cli/reference/formats/dot-strings-files) |
| `dotStringsdict` | `.stringsdict` 複数形ファイル。`.lproj` ディレクトリ内にロケールごとに 1 つ。 | [.stringsdict](/docs/cli/reference/formats/dot-stringsdict-files) |
| `androidStrings` | Android の `strings.xml` リソースファイル。 | [Android strings.xml](/docs/cli/reference/formats/android-strings-files) |
`dotStrings` と `dotStringsdict` には `gt` 2.18.1 以降、`androidStrings` には `gt` 2.19.0 以降、`xcstrings` には `gt` 2.21.0 以降、`srt` には `gt` 2.22.2 以降が必要です。
**v2.18.1 での変更点:** Apple 系ファイルのキーが `strings`、`stringsdict` から `dotStrings`、`dotStringsdict` に変更されました。以前のキーは現在のリリースでは認識されません。
### ファイルタイプのキー
各ファイルタイプでは、次のキーを使用できます。
* `include` — 翻訳対象のファイルに一致する glob パターンの配列です。`[locale]` プレースホルダーを使用します。CLI はこれを `defaultLocale` に置き換えてソースファイルを見つけ、各ターゲットコードに置き換えて翻訳を保存します。`gt` を除くすべてのタイプで必須です。
* `exclude` — スキップする glob パターンの配列です。ここでは `[locale]` プレースホルダーは任意です。すべてのロケールにまたがってパスを除外するには `[locales]` を使用します。
* `transform` — 出力ファイル名を変換します。`*` ワイルドカードを含む文字列は拡張子を変換します (例: `*.[locale].json`) 。`match` と `replace` を持つオブジェクトでは、正規表現のキャプチャグループと [ロケールプレースホルダー](#locale-placeholders) のロケールプレースホルダーを使用できます。
* `transformationFormat` — source とは異なる形式で翻訳済みファイルを出力します。たとえば、`"transformationFormat": "PO"` を指定した `pot` source からは `.po` ファイルが生成されます。
* `requiresReview` — 翻訳済みファイルを人手によるレビュー後にのみ公開されるようにします。`true`/`false`、または `include` と `exclude` の glob 配列を持つオブジェクトを指定できます。この場合、`exclude` が優先されます。
* `output` — `gt` ファイル専用で、`public/i18n/[locale].json` のように `[locale]` プレースホルダーを含むローカルの保存パスです。Locadex の workflow がトップレベルの CDN への公開なしで **Preserve local edits** を使用する場合に必須です。[Locadex の local edits の保持](#locadex-requirements) を参照してください。
* `parsingFlags` — `gt` ファイル専用で、インラインコンテンツの解析を制御するフラグです。[`autoderive`](/docs/cli/guides/using-autoderive) と [自動 JSX インジェクション](/docs/cli/guides/using-auto-jsx) を参照してください。
```json title="gt.config.json"
{
"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"]
}
}
}
```
### ロケールプレースホルダー [#locale-placeholders]
オブジェクトの `transform` における `replace` 値では、対象ロケールのプロパティに展開される `{...}` プレースホルダーを使用できます。認識されない名前は、リテラルテキストとして出力にそのまま残ります。
| プレースホルダー | 説明 | `pt-BR` の例 |
| -------------------- | ----------------------------------------------------------------- | ---------------------- |
| `{locale}` | [`locales`](#locales) に記述されたロケール表記そのものです。`{localeCode}` はエイリアスです。 | `pt-BR` |
| `{localeName}` | リージョンを含むロケールの英語名。 | `Brazilian Portuguese` |
| `{localeNativeName}` | リージョンを含むロケールの現地語名。 | `português (Brasil)` |
| `{languageCode}` | 言語サブタグのみ。 | `pt` |
| `{regionCode}` | リージョンサブタグのみ。 | `BR` |
| `{scriptCode}` | スクリプトサブタグのみ。 | `Latn` |
| `{minimizedCode}` | 曖昧さのない最短のタグ形式。 | `pt` |
| `{maximizedCode}` | スクリプトを含む完全なタグ形式。 | `pt-Latn-BR` |
| `{emoji}` | ロケールに対応する旗の絵文字。 | 🇧🇷 |
残りの [`LocaleProperties`](/docs/platform/core/reference/types/locale-properties) フィールドも名前で指定できます。これには `languageName`、`nativeLanguageName`、`regionName`、`nativeRegionName`、`scriptName`、`nativeScriptName`、`nameWithRegionCode`、`nativeNameWithRegionCode`、`maximizedName`、`nativeMaximizedName`、`minimizedName`、`nativeMinimizedName` が含まれます。
`{locale}` は正規の BCP-47 形式ではなく、設定で指定した表記を使用します。そのため、ロケールを `fr-ca` として設定した場合は、`fr-CA` ではなく `fr-ca` が生成されます。これは `include`、`exclude`、`output` 内の `[locale]` プレースホルダーと同じ動作であり、ファイルパスとローカライズされた URL の表記が一致します。正規化されたタグが必要な場合は、`{minimizedCode}`、`{maximizedCode}`、または `{regionCode}` を使用してください。
唯一の例外は [`androidStrings`](/docs/cli/reference/formats/android-strings-files) で、この場合はどちらのプレースホルダーも Android のリソースディレクトリ修飾子に展開されます (`fr-CA` は `fr-rCA` になります) 。これは、Android が解析できない `values-*` ディレクトリ名があるとビルドに失敗するためです。
```json title="gt.config.json"
{
"files": {
"json": {
"include": ["locales/[locale]/**/*.json"],
"transform": {
"match": "locales/(.*)/(.*)\\.json",
"replace": "locales/{locale}/$2.{languageCode}.json"
}
}
}
}
```
## `fonts` [#fonts]
**型** `object` · **任意** · **デフォルト** —
翻訳ジョブの実行前にアップロードするフォントファイル。プロジェクトルートを基準に解決される `include` と、任意の `exclude` glob を使用します。`.ttf` および `.otf` ファイルに一致します。CLI はこれらをバイナリデータとして読み取り、Lottie のレイアウト処理用の永続的な Organization asset としてアップロードします。
| プロパティ | 説明 | 型 | 任意 | デフォルト |
| --------- | ------------------------- | ---------- | --- | ----- |
| `include` | アップロードするフォントの glob パターン。 | `string[]` | いいえ | — |
| `exclude` | 一致したファイルから除外する glob パターン。 | `string[]` | はい | `[]` |
```json title="gt.config.json"
{
"fonts": {
"include": ["public/fonts/**/*.{ttf,otf}"],
"exclude": ["public/fonts/legacy/**"]
}
}
```
CLI は、新しい処理をキューに追加する [`gt stage`](/docs/cli/reference/commands/stage)、[`gt upload`](/docs/cli/reference/commands/upload)、[`gt enqueue`](/docs/cli/reference/commands/enqueue)、および [`gt translate`](/docs/cli/reference/commands/translate) の実行前に、該当するフォントを同期します。`stageTranslations` が有効な場合、[`gt translate`](/docs/cli/reference/commands/translate) はステージング済みのバージョンのみをダウンロードし、フォントは同期しません。フォントの同期に失敗すると警告が出力されますが、翻訳処理は停止しません。Lottie の処理はフォールバックフォントを使用して継続されます。フォントの検証と保存の動作については、[プロジェクトアセットをアップロード](/docs/platform/openapi/reference/project/upload-assets) を参照してください。
## `publish` [#publish]
**型** `boolean` · **任意** · **デフォルト** `false`
`true` の場合、[`translate`](/docs/cli/reference/commands/translate)、[`upload`](/docs/cli/reference/commands/upload)、または [`save-local`](/docs/cli/reference/commands/save-local) の実行後に、翻訳済みファイルが General Translation CDN に公開されます。Lottie の翻訳は API および CLI からのダウンロードでのみ利用できます。`publish` を設定しても、`.lottie` ファイルを CDN から利用できるようにはなりません。ファイル単位およびコマンド単位での制御については、[CDN 公開](#cdn-publishing) を参照してください。
```json title="gt.config.json"
{
"publish": true
}
```
## `stageTranslations` [#stage]
**型** `boolean` · **任意** · **デフォルト** `false`
`true` の場合、CLI は [`gt stage`](/docs/cli/reference/commands/stage) で送信されたバージョンのみをダウンロードします。CLI は、初めて [`gt stage`](/docs/cli/reference/commands/stage) を実行した際に、これを自動的に設定します。人手によるレビューや [Lottie](/docs/cli/reference/formats/lottie-files) などの非同期フォーマットには、ステージングワークフローを使用してください。完了した翻訳にも承認が必要かどうかは、プロジェクトのレビュー設定によって決まります。
## `requiresReview` [#requires-review]
**型** `boolean` · **任意** · **デフォルト** `false`
レビュー必須設定のプロジェクト全体のデフォルト値です。`true` の場合、翻訳済みの成果物は、クライアントが使用する前に承認が必要になります。指定できる値は boolean のみです。glob 単位の overrides には、ファイルごとの [`files..requiresReview`](#files) キー (boolean または `{ include, exclude }` の glob を受け付けます) を使用してください。ファイルごとのポリシーが優先され、`include` と `exclude` のどちらの glob にも一致しないファイルには、このトップレベルのデフォルト値が適用されます。
```json title="gt.config.json"
{
"requiresReview": true
}
```
## `src` [#src]
**型** `string[]` · **任意** · **デフォルト** フレームワークごとのソース glob
インラインコンテンツを検出するためにスキャンされるソースファイルの glob パターンの配列です。React 系のプロジェクトでは、デフォルトで `src`、`app`、`pages`、`components` 配下の JavaScript および TypeScript をスキャンします。Vue プロジェクトでは、ルートの `*.vue` ファイルに加えて、`composables`、`layouts`、`plugins`、`server`、`stores`、`utils`、`views` といった Vue や Nuxt の慣例的なディレクトリ内の JavaScript、TypeScript、Vue ファイルもスキャンします。
```json title="gt.config.json"
{
"src": [
"src/**/*.{js,jsx,ts,tsx}",
"app/**/*.{js,jsx,ts,tsx}",
"pages/**/*.{js,jsx,ts,tsx}",
"components/**/*.{js,jsx,ts,tsx}"
]
}
```
## `dictionary` [#dictionary]
**型** `string` · **任意** · **デフォルト** —
dictionary ファイルへの相対パスを指定します。省略した場合、CLI は `./src` と `./` 内で `dictionary.[json|ts|js]` を探します。
```json title="gt.config.json"
{
"dictionary": "./dictionary.json"
}
```
## `branchOptions` [#branch-options]
**型** `object` · **任意** · **デフォルト** —
ブランチごとの翻訳追跡を設定します。[ブランチごとの翻訳追跡](/docs/cli/guides/branching)を参照してください。CLI フラグはこれらの値より優先されます。
| プロパティ | 説明 | 型 | 任意 | デフォルト |
| -------------------- | ------------------------------- | --------- | -- | -------- |
| `enabled` | プロジェクトで Branching を有効にします。 | `boolean` | はい | `false` |
| `currentBranch` | 検出されたブランチ名を上書きします。 | `string` | はい | — |
| `autoDetectBranches` | 送信元ブランチとチェックアウト中のブランチの関係を検出します。 | `boolean` | はい | `true` |
| `remoteName` | ブランチ検出に使用する Git リモート名です。 | `string` | はい | `origin` |
```json title="gt.config.json"
{
"branchOptions": {
"enabled": true,
"currentBranch": "my-feature-branch",
"autoDetectBranches": true,
"remoteName": "origin"
}
}
```
## `customMapping` [#custom-mapping]
**型** `object` · **任意** · **デフォルト** —
ロケールを別のコードにエイリアスし、必要に応じてそのプロパティを上書きします。たとえば、`cn` を公式コード `zh` のエイリアスにできます。
エイリアスを使用する場合は、`defaultLocale` と `locales` のエントリには、正規な名前 (`zh`) ではなくエイリアス名 (`cn`) を指定してください。
```json title="gt.config.json"
{
"defaultLocale": "cn",
"locales": ["cn", "fr", "en"],
"customMapping": {
"cn": {
"code": "zh",
"name": "Mandarin"
}
}
}
```
## `options.saveLocal` [#save-local]
**型** `boolean` · **任意** · **デフォルト** `false`
以前にダウンロードしたローカル翻訳ファイル内の編集を検出し、[`gt translate`](/docs/cli/reference/commands/translate) または [`gt stage`](/docs/cli/reference/commands/stage) が新しいジョブをキューに追加する前に、その差分を送信します。トップレベルの `options` オブジェクト内に設定します。`--save-local` および `--no-save-local` フラグを使うと、1 回の実行に限りこの設定を上書きできます。
```json title="gt.config.json"
{
"options": {
"saveLocal": true
}
}
```
### バージョン履歴
| バージョン | 変更内容 |
| -------- | ------------------------------------------------------------------------------------------ |
| `2.20.3` | local edits が opt-in 方式になりました。この key を `true` に設定するか、`--save-local` を指定して step を有効にしてください。 |
## CDN 公開 [#cdn-publishing]
デフォルトでは、CLI は CDN に公開しません。プロジェクトの設定で CDN を有効にすると、公開をグローバル、ファイルごと、またはコマンドごとに制御できます。
* **グローバル:** トップレベルの [`publish`](#publish) を `true` に設定するか、[`translate`](/docs/cli/reference/commands/translate)、[`upload`](/docs/cli/reference/commands/upload)、または [`save-local`](/docs/cli/reference/commands/save-local) に `--publish` を渡します。
* **GT ファイルのみ:** `files.gt` の下で `publish: true` を設定します。
* **ファイルごと:** `include` 配列で、グロブ文字列を `pattern` と `publish` を持つオブジェクトに置き換えることで、一致したファイルを公開対象に含めるか除外するかを指定します。
```json title="gt.config.json"
{
"files": {
"json": {
"include": [
{ "pattern": "locales/[locale]/*.json", "publish": true },
{ "pattern": "locales/[locale]/internal/**/*.json", "publish": false }
]
}
}
}
```
任意のファイルについて、CLI は公開するかどうかを次の順序で判断します。まず明示的な `"publish": false` によるオプトアウト、次に明示的な `"publish": true` によるオプトイン、最後にグローバルの `publish` 設定です。どのレベルにも公開設定が存在しない場合、公開ステップはスキップされます。
## Locadex のローカル編集の保持 [#locadex-requirements]
Locadex の自動化で **Preserve local edits** が有効になっている場合は、トップレベルの `"publish": true` または `files.gt.output` のいずれかを設定してください。Locadex は翻訳を実行する前にこの設定を検証します。
```json title="gt.config.json"
{
"files": {
"gt": {
"output": "public/i18n/[locale].json"
}
}
}
```
ファイル単位の設定や `files.gt.publish` の設定では、このチェックは満たされません。トップレベルでのCDN公開を行わない場合は、`files.gt.output` によってローカルのGTJSON翻訳の保存場所がワークフローに伝わり、編集内容を保持できるようになります。
## 設定例 [#example]
```json title="gt.config.json"
{
"$schema": "https://assets.gtx.dev/config-schema.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/reference/commands/translate) を1回実行するだけで、`content/docs/en` 配下の MDX ファイル (`.fr.mdx` と `.es.mdx` として `content/docs/fr` および `content/docs/es` に保存) 、`resources/en` 配下の JSON ファイル (`resources/en/exclude` を除く) 、さらにインラインの [``](/docs/react/reference/components/t) コンポーネントと dictionary エントリが翻訳されます。GT の翻訳は `public/i18n/fr.json` と `public/i18n/es.json` に保存されます。
## Sitemap
See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.