# gt: General Translation CLI tool: キーごとのメタデータ
URL: https://generaltranslation.com/ja/docs/cli/reference/keyed-metadata.mdx
---

title: キーごとのメタデータ
description: General Translation の JSON ファイルおよび YAML ファイルに、キーごとの翻訳指示を付与します。キーごとのメタデータの API リファレンス。

---

ソースファイルのキー構造を反映した補助メタデータファイルを用意し、各末端にメタデータオブジェクトを配置します。各オブジェクトには、そのキーの翻訳に関する指示が含まれます。

CLI は補助メタデータファイルを自動的に検出し、ソース構造に照らして検証したうえで、翻訳エンジンに送信します。

## フィールド [#fields]

| フィールド                        | 説明                           | 型        | 任意 | デフォルト |
| ---------------------------- | ---------------------------- | -------- | -- | ----- |
| [`context`](#context)        | 特定の文字列に対する翻訳指示。              | `string` | はい | —     |
| [`maxChars`](#max-chars)     | 翻訳後の出力の最大文字数。                | `number` | はい | —     |
| [`sourceCode`](#source-code) | ファイルパスをキーとする周辺のソースコードコンテキスト。 | `object` | はい | —     |

## ファイル構造 [#structure]

補助メタデータファイルは、ソースファイルと同じディレクトリに配置し、`{name}.metadata.{ext}` という命名規則に従い、各末端にメタデータオブジェクトを持つ形でソースファイルのキー構造を反映している必要があります。

```text
translations.json           # ソース文字列
translations.metadata.json  # キーごとのメタデータ
```

特定の翻訳指示が必要なキーに対してのみ、エントリを追加してください。エントリのないキーは通常どおり翻訳されます。

```json title="translations.json"
{
  "nav": {
    "home": "Home",
    "bank": "Bank",
    "save": "Save"
  }
}
```

```json title="translations.metadata.json"
{
  "nav": {
    "bank": {
      "context": "川岸 — 川の側面。金融機関ではない。"
    },
    "save": {
      "context": "スポーツ用語 — ゴールキーパーがゴールを防ぐこと。データの保存ではない。",
      "maxChars": 12
    }
  }
}
```

## `context` [#context]

**型** `string` · **任意** · **デフォルト** —

特定の文字列に対して適用する翻訳指示です。複数の意味を持つ語の曖昧さを解消したり、ドメイン固有の用語を指定したり、意図する解釈を明確にしたりするために使用します。

```json
{
  "bank": {
    "context": "Riverbank. The side of a river where land meets water, NOT a financial institution."
  }
}
```

## `maxChars` [#max-chars]

**型** `number` · **任意** · **デフォルト** —

翻訳結果に対する最大文字数制限です。エンジンは制限内に収めるため、より短い同義語や略語、簡潔な言い回しを使用します。これはベストエフォートです。ソース内容に対してこの制限を満たすのが現実的でない場合は、完全な翻訳が返されます。

```json
{
  "save": {
    "maxChars": 10
  }
}
```

## `sourceCode` [#source-code]

**型** `object` · **任意** · **デフォルト** —

文字列の周辺ソースコードコンテキスト。ファイルパスをキーとし、各エントリには `before` (対象行より上の行) 、`target` (文字列を含む行) 、`after` (対象行より下の行) が含まれます。同じ文字列が異なる場所に出現する場合は、1 つのファイルに複数のエントリを含められます。

```json
{
  "new_lead": {
    "sourceCode": {
      "components/Dashboard.tsx": [
        {
          "before": "function NotificationBanner({ type }) {\n  const gt = useGT();",
          "target": "  const msg = gt('You have a new lead!');",
          "after": "  return <Banner variant=\"success\">{msg}</Banner>;\n}"
        }
      ]
    }
  }
}
```

### 組み合わせの例

1 つのキーに 3 つのフィールドをすべてまとめた例:

```json
{
  "save_button": {
    "context": "Sports term. A goalkeeper's save — preventing a goal from being scored. NOT saving data.",
    "maxChars": 12,
    "sourceCode": {
      "components/MatchStats.tsx": [
        {
          "before": "const stats = useMatchStats();\nconst gt = useGT();",
          "target": "const label = gt('セーブ');",
          "after": "return <StatBadge icon={<GoalkeeperIcon />}>{label}: {stats.saves}</StatBadge>;"
        }
      ]
    }
  }
}
```

## YAML [#yaml]

Metadata は `.metadata.yaml` または `.metadata.yml` の補助ファイルでも同様に機能します。

```yaml title="translations.metadata.yaml"
ui:
  buttons:
    save:
      context: "Sports term. A goalkeeper's save, NOT saving data."
      maxChars: 12
  labels:
    date:
      context: "The edible fruit of the date palm. NOT a calendar date."
```

## 検証 [#validation]

CLI はメタデータファイルをソース構造に照らして検証し、メタデータキーがソースに存在しない場合、値の型がソースと一致しない場合 (プリミティブかオブジェクトか、配列かオブジェクトか) 、ルートの型が一致しない場合、またはファイルを解析できない場合は、エラーを出して終了します。

## スキーマとマッチング [#schema]

キーごとのメタデータは、JSON スキーマ (`include` と `composite`) および YAML スキーマ (`include`) で使用できます。メタデータは同じスキーマパイプラインを通して変換されるため、翻訳時に key パスが一致します。companion ファイルは対応するソースファイルとマッチングされ、それ単体では翻訳されません — 対応するソースがない `.metadata.json` ファイルは通常のファイルとして扱われます。メタデータだけを変更しても再翻訳はトリガーされません。ソースコンテンツも変更されている必要があります。