ダッシュボード

構成

gt.config.json ファイルの設定に関するドキュメント

概要

gt.config.json は、プロジェクトの GT 設定を行うためのファイルです。プロジェクトのルートディレクトリに配置してください。

CLI のセットアップウィザード npx gtx-cli init を実行すると、プロジェクト内に gt.config.json が作成されます。

設定

gt.config.json ファイルでは、以下のプロパティを使用できます（これらに限りません）。

  • defaultLocale: プロジェクトの既定のロケール。ソースコンテンツが記述されているロケールです（gt-next または gt-react を使用している場合は、プロジェクトのフォールバックロケールにもなります）。

  • locales: プロジェクトの対応ロケールの配列。プロジェクトをどのロケールに翻訳するかを指定します。詳しくは supported locales を参照してください。 gt-next または gt-react を使用している場合、これはアプリがサポートするロケールにもなります。

  • files: 翻訳対象のコンテンツに関する情報を含むオブジェクト。

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

  • src: ソースファイルのファイルグロブパターンを指定する任意の配列。既定では次のように設定されます:

[
  "src/**/*.{js,jsx,ts,tsx}",
  "app/**/*.{js,jsx,ts,tsx}",
  "pages/**/*.{js,jsx,ts,tsx}",
  "components/**/*.{js,jsx,ts,tsx}"
]
  • dictionary: dictionary ファイルへの相対パスを指定する任意の文字列です。

gt.config.json を検証するには、CLI 用の JSON Schema を利用できます。

gt.config.json の先頭に次を追加してください:

gt.config.json
{
  "$schema": "https://assets.gtx.dev/config-schema.json",
}

以下は gt.config.json のひな型です:

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"
}

locale のエイリアス設定

locale にエイリアスを設定したい場合（例: zh の代わりに cn を使う）、gt.config.json ファイルでカスタムマッピングを指定できます。

gt.config.json
{
  "customMapping": {
    "cn": {
      "code": "zh",
    }
  }
}

エイリアス先のlocaleに対して、別の属性を指定することもできます。

gt.config.json
{
  "customMapping": {
    "cn": {
      "code": "zh",
      "name": "中国語（標準）",
    }
  }
}

files

対応ファイルタイプ

files には、翻訳したい各ファイルタイプごとのキーを含めてください。 プロジェクトでは異なるファイルタイプを組み合わせて設定でき、すべてを翻訳対象にできます。 現在サポートしているファイルタイプは次のとおりです。

  • gt: General Translation のファイル。
  • json: JSON ファイル。
  • yaml: YAML ファイル。
  • mdx: Markdown コンポーネント（MDX）ファイル。
  • md: Markdown（MD）ファイル。
  • js: JavaScript ファイル。
  • ts: TypeScript ファイル。

各ファイルタイプは、以下のキーのうち 1 つ以上を含むオブジェクトに対応させてください。

  • include
  • exclude
  • transform
  • output

include

使用する場合、include キーの value は、翻訳対象の files にマッチするグロブパターンの配列にしてください。

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

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

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

exclude

使用する場合、exclude キーの value には、翻訳から除外したい files にマッチするグロブパターンの配列を指定します。

パターンは include と同じですが、[locale] プレースホルダーは任意です。指定した場合は、defaultLocale の値に置き換えられます。

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

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

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

transform

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

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

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

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

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

  • match（任意）：文字列に一致させる正規表現パターン。キャプチャグループをサポート
  • replace（必須）：一致部分を置換するための文字列または正規表現パターン

両方の値は正規表現のキャプチャグループをサポートし、出力ファイルの相対パス（ファイル名全体）に対応付けられます。

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

たとえば、上記の設定では、翻訳済みの files はターゲットの locale のサブディレクトリに保存されます。

特別なプレースホルダー

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 の他の任意のプロパティも、同様のコンテキスト依存の動作でプレースホルダーとして使用できます。

ドキュメントや i18n フレームワークが、サブディレクトリベースのロケールルーティングではなく、翻訳ファイルに特定のファイル拡張子を求める場合に有用です。

output

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

value は、翻訳の保存先を示す [locale] プレースホルダーを含む文字列である必要があります。

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

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

このオプションは、gt-next または gt-react を使用していて、GT CDN を使わずに翻訳をローカルに保存したい場合にのみ使用してください。

現在、各localeにつき生成できるファイルは1つだけです。

ファイルタイプ: gt

サポートされるキー

  • output（必須）

例

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

この構成では、CLI ツールがフランス語とスペイン語の翻訳を public/i18n/[locale].json ディレクトリに保存するようになります。

既定では、この構成のままでは CLI ツールは翻訳を GT CDN に公開しません。

ファイルタイプ: json

サポートされるキー

  • include（必須）
  • exclude（任意）
  • transform（任意）

例

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

プロジェクトの既定のlocaleが en で、プロジェクトを fr と es に翻訳したいとします。

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

サブディレクトリ json_files/en/exclude/ にあるファイルは無視されます。

ファイルタイプ: yaml

サポートされているキー

  • include（必須）
  • exclude（任意）
  • transform（任意）

例

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

たとえば、プロジェクトのデフォルトの locale が en で、fr と es への翻訳を行いたいとします。

この設定では、CLI はサブディレクトリ yaml_files/en/ 配下のすべての YAML ファイルを探索し、翻訳結果を yaml_files/fr/ および yaml_files/es/ に保存します。

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

ファイルタイプ: mdx

対応キー

  • include（必須）
  • exclude（任意）
  • transform（任意）

使用例

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

サポートされるキー

  • include（必須）
  • exclude（任意）
  • transform（任意）

例

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

サポートされるキー

  • include（必須）
  • exclude（任意）
  • transform（任意）

例

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

この設定は、CLI ツールに scripts/en ディレクトリ配下のすべての JavaScript ファイルを検索し、翻訳済みファイルを scripts/fr と scripts/es ディレクトリに保存するよう指示します。

transform キーによって、翻訳済みファイルの拡張子は（.js から）それぞれ .fr.js と .es.js に変更されます。

ファイルタイプ: ts

サポートされるキー

  • include（必須）
  • exclude（任意）
  • transform（任意）

例

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

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

transform キーにより、翻訳済みファイルの拡張子は（.ts から）それぞれ .fr.ts と .es.ts に変更されます。

設定例

gt.config.json ファイルの例をかみ砕いて説明します：

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"]
    }
  }
}

この例では、gtx-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 で読み込めます。

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

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

次のステップ

init コマンドの使い方を学び、この構成ファイルを生成しましょう。

このガイドはどうでしたか？

TypeScript

General Translation を使って TypeScript/JavaScript ファイルを自動翻訳する方法

使い方ガイド

GT コマンドラインツールの使い方ガイド

このページについて

概要
設定
locale のエイリアス設定
files
対応ファイルタイプ
include
exclude
transform
特別なプレースホルダー
output
ファイルタイプ: gt
ファイルタイプ: json
ファイルタイプ: yaml
ファイルタイプ: mdx
ファイルタイプ: md
ファイルタイプ: js
ファイルタイプ: ts
設定例
次のステップ
構成