# gt: General Translation CLI tool: キーごとのメタデータ
URL: https://generaltranslation.com/ja/docs/cli/reference/keyed-metadata.mdx
---
title: キーごとのメタデータ
description: JSON および YAML ファイル向けのキー単位の翻訳メタデータ
---

## 概要

キーごとのメタデータを使うと、JSON ファイルや YAML ファイル内の各キーに翻訳指示を付けられます。ソースファイルのキー構造に対応した `.metadata.json` または `.metadata.yaml` の補助ファイルを用意し、末端のキーにメタデータオブジェクトを配置します。

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

***

## ファイル構造

補助メタデータファイルは、次の要件を満たしている必要があります。

* ソースファイルと同じディレクトリに配置する
* `{name}.metadata.{ext}` という命名規則に従う (例: `translations.json` に対して `translations.metadata.json`) 
* ソースファイルのキー構造を反映する

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

メタデータファイルはソースキーの構造をそのまま反映しており、末端の値には文字列ではなくメタデータオブジェクトが入ります。

```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": {
    "bank": {
      "context": "川岸 — 川の側面。金融機関ではない。"
    },
    "save": {
      "context": "スポーツ用語 — ゴールキーパーがゴールを防ぐこと。データの保存ではない。",
      "maxChars": 12
    }
  },
  "alerts": {
    "new_lead": {
      "context": "営業/CRMのコンテキスト。'lead'は見込み客のこと。",
      "maxChars": 30
    }
  }
}
```

すべてのキーにメタデータが必要なわけではありません。`home` には上記のエントリがなくても、通常どおり翻訳されます。特定の翻訳指示が必要なキーに対してのみ、エントリを追加してください。

***


## フィールドリファレンス

| フィールド        | 型                                                                     | 必須  | 説明                           |
| ------------ | --------------------------------------------------------------------- | --- | ---------------------------- |
| `context`    | `string`                                                              | いいえ | この文字列に固有の翻訳指示                |
| `maxChars`   | `number`                                                              | いいえ | 翻訳後の出力の最大文字数                 |
| `sourceCode` | `Record<string, { before: string; target: string; after: string }[]>` | いいえ | ファイルパスをキーとした、前後のソースコードコンテキスト |

***

## フィールド

### `context`

型: `string`

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

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


### `maxChars`

型: `number`

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

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


### `sourceCode`

型: `Record<string, { before: string; target: string; after: string }[]>`

文字列の周辺ソースコードコンテキスト。ファイルパスをキーとし、各エントリには次が含まれます。

* `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": "スポーツ用語。ゴールキーパーのセーブ（得点を防ぐこと）。データの保存ではない。",
    "maxChars": 12,
    "sourceCode": {
      "components/MatchStats.tsx": [
        {
          "before": "const stats = useMatchStats();\nconst gt = useGT();",
          "target": "const label = gt('Save');",
          "after": "return <StatBadge icon={<GoalkeeperIcon />}>{label}: {stats.saves}</StatBadge>;"
        }
      ]
    }
  }
}
```

***


## YAML

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

```yaml title="translations.metadata.yaml"
ui:
  buttons:
    save:
      context: "Sports term. A goalkeeper's save, NOT saving data."
      maxChars: 12
    draft:
      context: "Beer on tap, as in 'draft beer'. NOT a document version."
  labels:
    date:
      context: "The edible fruit of the date palm. NOT a calendar date."
```

***


## 検証

CLI は、ソースファイルの構造に基づいてメタデータファイルを検証します。次の場合、プロセスはエラーで終了します。

* メタデータのキーがソースファイルに存在しない
* ソースではネストされたオブジェクトになっている箇所で、メタデータの値がプリミティブである
* ソースではオブジェクトになっている箇所で、メタデータの値が配列である (またはその逆) 
* ルートの型 (配列またはオブジェクト) がソースと一致しない
* メタデータファイルをパースできない

***

## スキーマ対応

キーごとのメタデータは、JSON スキーマ (`include` および `composite`) と YAML スキーマ (`include`) に対応しています。メタデータはソースコンテンツと同じスキーマパイプラインを通して自動的に変換されるため、ファイル構造に関係なく、翻訳時のキーパスは一致します。

***

## 補助ファイルのフィルタリング

補助メタデータファイルは、対応するソースファイルに自動的に紐付けられます。これらが独立したファイルとして翻訳されることはありません。これは、対応するソースファイルがファイル一覧に存在する場合にのみ適用されます。一致するソースファイルがない `.metadata.json` ファイルは、通常のファイルとして扱われます。

***

## 再翻訳の挙動

ソースコンテンツに変更がない場合、メタデータファイルだけを変更しても再翻訳は実行されません。更新したメタデータを反映するには、ソースコンテンツも変更する必要があります。