ブログダッシュボード

設定

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 キーの値は、翻訳対象のファイルに一致するグロブパターンの配列である必要があります。

ソースファイルを正しく検出し、翻訳後のファイルを正しい場所に保存するため、グロブパターンでは必ず [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 のサブディレクトリに保存されます。

特殊プレースホルダー

The transform option supports several special placeholders that can be used in both match and replace strings:

  • {locale}: The locale code placeholder that behaves differently depending on context:
    • In match strings: Replaced with the default locale code (e.g., "en") to help identify source files
    • In replace strings: Replaced with the target locale code (e.g., "fr", "es") for the translated output files

For example, if your default locale is "en" and you're translating to "fr":

  • A match pattern of "content/{locale}/file.md" becomes "content/en/file.md"
  • A replace pattern of "content/{locale}/file.md" becomes "content/fr/file.md"

Additionally, any other property from getLocaleProperties can be used as a placeholder with the same context-dependent behavior.

This is useful if your docs or i18n framework requires a specific file extension for translated files instead of subdirectory-based locale routing.

output

このキーはGeneral Translationのfilesでのみ使用され、主に翻訳をローカルに保存するためのものです。GTのCDN（コンテンツ配信ネットワーク）を使用している場合、このキーは不要です。

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

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

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

プロジェクトのデフォルトのロケールが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
設定例
次のステップ