# General Translation Changelog: gtx-cli 2.10.0: キーごとの翻訳指示
URL: https://generaltranslation.com/ja/blog/gtx-cli_v2_10_0.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 
Authors: Fernando Aviles
Published: 2026-03-12

## 概要

**gtx-cli 2.10.0** では、JSON および YAML の翻訳ファイルで **キー単位のメタデータ** をサポートしました。これはキーごとの翻訳指示で、個々の文字列をどう翻訳するかをきめ細かく制御できます。

これまで、キー付きファイルの翻訳コンテキストはプロジェクトレベルで管理されていました。スタイル制御、用語集エントリ、ロケール固有のルールは、すべてのコンテンツに一律で適用されていました。キー単位のメタデータを使うと、さらに細かく制御できるようになり、ファイル内の個々のキーに特定の翻訳ヒントを直接付与できます。

***

## 構成例

ソースファイルと同じ階層に、そのキー構造を反映した補助メタデータファイルを作成します。末端の階層では、文字列の代わりに翻訳指示を含むメタデータオブジェクトを指定します。

```json title="translations.json"
{
  "nav": {
    "home": "Home",
    "bank": "Bank",
    "save": "Save"
  },
  "alerts": {
    "new_lead": "You have a new lead!"
  }
}
```

```json title="translations.metadata.json"
{
  "nav": {
    "home": {
      "context": "野球用語 — ダイヤモンドのホームベース。家（住居）ではない。"
    },
    "bank": {
      "context": "川岸 — 川の側面。金融機関ではない。"
    },
    "save": {
      "context": "スポーツ用語 — ゴールキーパーによるセーブ。データの保存ではない。",
      "maxChars": 12
    }
  },
  "alerts": {
    "new_lead": {
      "context": "営業/CRMの文脈。'lead'は見込み客を指す。",
      "maxChars": 30
    }
  }
}
```

補助メタデータファイルはソースファイルと同じディレクトリに置き、`{name}.metadata.json` (YAML ファイルでは `.metadata.yaml`) という命名規則に従う必要があります。CLI は [`npx gt translate`](/docs/cli/reference/commands/translate) を実行すると自動的にこれを読み込みます。

キーごとのコンテキストがあると、"Bank" は "Banco" (金融機関) ではなく "Ribera" (川岸) に、"Save" は "Guardar" (保存する) ではなく "Parada" (ゴールキーパーのセーブ) に翻訳されます。すでに意味が明確な文字列には、メタデータはまったく不要です。必要なキーにだけエントリを追加してください。

***

## サポートされているフィールド

現在、サポートしているメタデータフィールドは 3 つです。

* **`context`** — 特定の文字列に対する翻訳指示です。最も効果の大きいフィールドで、語義の曖昧さを解消したり、ドメイン固有の用語を指定したり、意図を明確にしたりするために使用します。
* **`maxChars`** — 翻訳結果の最大文字数制限です。これはベストエフォートで適用されます。エンジンは制限内に収めるため、より短い類義語や簡潔な表現を使いますが、無理な文字数に合わせて翻訳を切り詰めることはありません。
* **`sourceCode`** — 文字列の周辺にあるソースコードのコンテキストです。これにより、その文字列がコードベース内のどこでどのように使われているかをエンジンに示せるため、トーン、用語、表現についてより適切に判断できるようになります。

すべてのフィールドはキーごとに省略可能です。各フィールドの詳細と例については、[keyed metadata reference](/docs/cli/reference/keyed-metadata)を参照してください。

***

## YAML のサポート

同じ方法を YAML ファイルにも適用できます。同じキー構造を持つ `.metadata.yaml` の補助ファイルを作成します。

```yaml title="translations.metadata.yaml"
ui:
  buttons:
    save:
      context: "スポーツ用語 — ゴールキーパーのセーブ。データの保存（save）ではない。"
    draft:
      context: "生ビール（樽生）のこと。文書のドラフト（下書き・草稿）ではない。"
  labels:
    date:
      context: "ナツメヤシの食用果実のこと。カレンダーの日付（date）ではない。"
    chips:
      context: "英国英語：揚げたポテトの細切り（フライドポテト）のこと。ポテトチップス（crisps）や半導体チップ（microchips）ではない。"
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.