# General Translation Knowledge Base: YAML のロケールファイルはどのように翻訳すればよいですか？
URL: https://generaltranslation.com/ja/kb/translate-yaml-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 翻訳するのは文字列の値だけにし、キー、%{name} や {{name}} などのプレースホルダー、アンカーはそのまま残します。コロンを含む値や % または { で始まる値は引用符で囲み、各ファイルのロケールのルートキーまたはファイル名を設定し、対象言語に必要な複数形キーを追加します。General Translation の CLI は YAML の値をインプレースで翻訳し、キーには手を加えません。
Category: 翻訳
Last updated: 2026-10-28
Authors: General Translation Team
Published: 2026-10-28

YAML のロケールファイルは、キーとユーザー向けの文字列を対応付けるもので、言語ごとに 1 つのファイル (または 1 つのトップレベルキー) を使います。翻訳では、キー、プレースホルダー、ファイル構造をフレームワークが想定するとおりに保ったまま、文字列の値だけを置き換えます。YAML では、これが JSON よりも難しくなります。引用符で囲まれていないコロンや先頭の `%` はパースエラーの原因となり、`no` は真偽値として解釈されることがあります。そのため、訳文自体は正しくても、アプリに読み込みを拒否されたり、誤って解釈されたりするファイルになってしまうおそれがあります。

## YAMLの代表的なロケール構成

言語を指定する場所やプレースホルダーの構文はフレームワークごとに異なり、翻訳済みファイルもそれぞれのルールに従う必要があります。

| フレームワーク                                                                                                      | ソースファイル                         | 言語の指定場所                       | プレースホルダー                                | 複数形                                           |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------- | ----------------------------- | --------------------------------------- | --------------------------------------------- |
| [Rails I18n](https://guides.rubyonrails.org/i18n.html)                                                       | `config/locales/en.yml`         | トップレベルのキー (`en:`)             | `%{name}`                               | `one` と `other` のキー (rails-i18n を使うとさらに追加可能)  |
| [Symfony](https://symfony.com/doc/current/translation.html#translation-resource-file-names-and-locations)    | `translations/messages.en.yaml` | ファイル名 (`domain.locale.yaml`)  | `%name%` (`+intl-icu` ファイルでは `{name}`)  | 文字列内に ICU 形式で記述                               |
| [Hugo](https://gohugo.io/functions/lang/translate/#translation-tables)                                       | `i18n/en.yaml`                  | ファイル名                         | `{{ . }}` などの Go テンプレート                 | CLDR のキー (`one`、`few`、`many`、`other`)         |
| i18next + [i18next-fs-backend](https://github.com/i18next/i18next-fs-backend)                                | `locales/en/common.yml`         | ディレクトリ                        | `{{name}}`                              | `_one` や `_other` などの接尾辞付きキー                  |
| vue-i18n + [unplugin-vue-i18n](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n) | `locales/en.yaml`               | ファイル名                         | `{name}`                                | 1つの文字列内にパイプ区切りで記述                             |

構造に最も厳格なのは Rails です。[Rails ガイド](https://guides.rubyonrails.org/i18n.html#configuring-the-load-paths-and-default-locale)によると、`config/locales` 配下のすべての `.yml` ファイルと `.rb` ファイルが読み込まれ、各ファイルでは「トップレベルのキーがロケールになります」。そのため、スペイン語のファイルはファイル名に関係なく `es:` で始める必要があります。

## 翻訳済みファイルを壊す YAML の落とし穴

以下は、すべての値が翻訳後も壊れないように書かれた Rails ファイルの例です。

```yaml title="config/locales/en.yml"
en:
  checkout:
    title: "Note: prices include VAT"
    joined: "%{name} joined your team"
    confirm_no: "No"
    terms: |
      By paying, you agree to our terms.
      Refunds take 5 to 7 days.
    items:
      one: "%{count} item"
      other: "%{count} items"
```

各行は、よくある失敗をそれぞれ防いでいます。

* **コロン。** `title: Note: prices include VAT` をクォートなしで書くと構文エラーになります。また、英語にはなかったコロンが翻訳で加わることもあります。
* **インジケーター文字で始まる値。** プレーンな値は `%`、`{`、`[`、`@`、バッククォートで始めることができません。`joined: %{name} joined your team` は解析に失敗し、`{{name}} joined` はマッピングの開始として解釈されます。翻訳では語順が変わるため、英語では文中にあったプレースホルダーが先頭に来ることはよくあります。Hugo の公式ドキュメントが `'{{ . }} day'` をクォートしているのもこのためです。
* **真偽値。** Ruby の YAML パーサーは YAML 1.1 に準拠しているため、クォートなしの `yes`、`no`、`on`、`off` は `true` や `false` になります。一方、ほとんどの JavaScript ツールを含む YAML 1.2 のパーサーは、これらを文字列として読み込みます。Rails ガイドには[これらのキーはエスケープする必要がある](https://guides.rubyonrails.org/i18n.html#configuring-the-load-paths-and-default-locale)と書かれており、値についても同様です。ノルウェー語のファイルでルートを `no:` にしただけでも、Ruby ではキー `false` の下に読み込まれてしまいます。
* **ブロックスカラー。** `|` は改行を保持し、`>` は改行をスペースに置き換えて 1 行にまとめます。翻訳後の行もブロックのインデントを維持する必要があり、崩れると値が途中で終わったり、ファイル全体が解析できなくなったりします。
* **アンカーとエイリアス。** `&name` でブロックを定義し、`*name` でそれを再利用します。そのため、アンカーを付けた値を変更すると、すべてのエイリアスに反映されます。Rails はこれらを読み込めますが、unplugin-vue-i18n は YAML リソースで[エイリアスをサポートしていない](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n)と明記しています。利用する前に、使用しているローダーが対応しているか確認してください。

`title` と `joined` の行をクォートなしにしてそれぞれ別のファイルに置くと、Ruby のパーサー (Ruby 2.6、Psych 3.1) は、Rails がキーを 1 つも読み込まないうちに両方ともエラーとして拒否します。

```text title="Output"
unquoted-colon.yml: mapping values are not allowed in this context at line 3 column 16
unquoted-placeholder.yml: found character that cannot start any token while scanning for the next token at line 3 column 13
```

すべての値を引用符で囲むのが最もシンプルなルールです。ダブルクォートで囲んだ文字列は常に文字列として扱われるため、`%{name}`、コロン、`No` もテキストのまま解釈されます。

### 複数形キーは言語によって異なる

英語では `one` と `other` を使いますが、ロシア語やポーランド語ではさらに `few` と `many` も必要です。キーが不足していてもエラーにはなりません。i18n gem の複数形処理バックエンドと、rails-i18n に同梱されているようなロシア語の複数形規則を使っている場合、英語からキーごとに翻訳したファイルでは、`few` が必要な数値すべてに対して、警告なしに `other` が使われてしまいます。以下のロシア語ファイルは、どちらも General Translation による翻訳です。

```text title="Output"
count  key-by-key (one, other)              complete (one, few, many, other)
1      У вас 1 непрочитанное сообщение.     У вас 1 непрочитанное сообщение.
3      У вас 3 непрочитанных сообщений.     У вас 3 непрочитанных сообщения.
5      У вас 5 непрочитанных сообщений.     У вас 5 непрочитанных сообщений.
22     У вас 22 непрочитанных сообщений.    У вас 22 непрочитанных сообщения.
```

[Rails ガイド](https://guides.rubyonrails.org/i18n.html#locale-specific-rules)にもあるとおり、デフォルトで適用されるのは英語の複数形規則だけで、それ以外の言語の規則は I18n の `Pluralization` バックエンドまたは rails-i18n gem で追加します。Hugo の翻訳テーブルも同じ CLDR カテゴリ (`zero` から `other` まで) を使用しています。

### ロケールのルートキーを変更する

Rails では、`en:` で始まったままの翻訳済みファイルがあってもエラーにはならず、英語として読み込まれてしまいます。i18n gem を使ったテストでは、ルートが `en:` のまま残ったスペイン語ファイルによって英語のタイトルがスペイン語で上書きされ、`es` に対する `I18n.t` は翻訳が見つからないというメッセージを返しました。すべての翻訳済みファイルでルートを変更し、`config.i18n.available_locales` とも同期させておきましょう。

## YAMLロケールファイルを翻訳する方法

| 方法                                                                                                           | キーとプレースホルダー               | 複数形キー                                           | 短い文字列の文脈                 | 変更への追従                        |
| ------------------------------------------------------------------------------------------------------------ | ------------------------- | ----------------------------------------------- | ------------------------ | ----------------------------- |
| 手作業                                                                                                          | 翻訳者がYAMLを理解していれば安全        | 翻訳者がその言語の規則を把握していれば追加される                        | 翻訳者が質問できる                | 変更のたびに手作業で対応                  |
| [i18n-tasks](https://github.com/glebm/i18n-tasks) `translate-missing` (Rails) ＋Google Translate、DeepL、OpenAI | 送信前に `%{...}` をトークンに置き換える | rails-i18nの規則を読み込んでいれば、`missing` が欠けている複数形を報告する | バックエンドごとのオプションとプロンプト     | 欠けているキーを補完するが、英語を編集しても再翻訳されない |
| 翻訳管理システム (TMS)                                                                                               | 形式に応じて解析                  | TMSによる                                          | スクリーンショット、コメント、用語集       | リポジトリ同期またはファイルの受け渡し           |
| ファイルを処理するLLMスクリプト                                                                                            | 通常は保持されるが、クォートが正しい保証はない   | 明示的に指示した場合のみ追加される                               | プロンプトに含めた内容次第            | 毎回再実行して検証が必要                  |
| [General TranslationのCLI](/docs/cli/reference/formats/yaml-files)                                            | 文字列の値のみを翻訳し、キーはそのまま       | 翻訳元にあるキーを翻訳する                                   | 用語集、カスタムプロンプト、キーごとのメタデータ | 実行のたびに変更のない翻訳を再利用する           |

小さなファイルが1〜2個程度なら、手作業での編集で十分です。Railsアプリで欠けているキーのチェックが必要で、機械翻訳で補った部分を自分でレビューする運用で問題なければ、i18n-tasksが適しています (両者の併用方法については [General Translation vs. i18n-tasks](/kb/general-translation-vs-i18n-tasks) を参照してください) 。翻訳者がファイルを管理する場合は [TMS](/kb/what-is-a-translation-management-system) を使いましょう。英語の変更に合わせてすべてのロケールファイルを再生成し、アプリ、ドキュメント、マーケティングサイト全体で用語を統一したい場合は、General Translationを使いましょう。

## General TranslationでYAMLファイルを翻訳する

General TranslationのCLIである`gt`は、`gt.config.json`に`yaml`エントリを追加すると、`.yaml`および`.yml`ファイルを翻訳します。`[locale]`プレースホルダーで言語が入る位置を指定するため、ファイル名にロケールを含む形式もそのまま使えます。Symfonyの場合、`translations/*.[locale].yaml`と指定すると`messages+intl-icu.en.yaml`が`messages+intl-icu.fr.yaml`に対応付けられます。Hugoの場合は次のとおりです。

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["de", "pt-BR"],
  "files": {
    "yaml": {
      "include": ["i18n/[locale].yaml"]
    }
  }
}
```

`gt` 2.26.11 で確認したところ、CLI のパス解決では `i18n/en.yaml` が `i18n/de.yaml` や `i18n/pt-BR.yaml` にマッピングされ、Hugo の言語タグ形式のファイル名と一致します。[`npx gt login`](/docs/cli/reference/commands/login) でサインインしてプロジェクトIDを設定し ([CLI の認証情報](/docs/cli/guides/configuring#credentials)) 、既存の翻訳があれば [`npx gt upload`](/docs/cli/reference/commands/upload) でインポートしてから、[`npx gt translate`](/docs/cli/reference/commands/translate) を実行します。

General Translation が翻訳するのは文字列の値だけで、それ以外には手を加えません。キー、数値、真偽値、コメントはそのまま残り、アンカー付きブロックは一度だけ翻訳され、そのエイリアスも引き続き同じブロックを参照します。そのため、フレームワーク固有の以下の点はご自身で対応する必要があります。

* **Rails のロケールルート。** CLI はトップレベルの `en:` を含め、キー名を変更しません。また、[`transform`](/docs/cli/reference/config#files) オプションで変更されるのは出力ファイル名であり、キーではありません。CLI 用には `translations/en.yml` のようなルートのない作業ファイルを用意し、`config/locales` にエクスポートする際にロケールルートを追加してください。 (簡単なエクスポートスクリプトについては [General Translation vs. Rails I18n](/kb/general-translation-vs-rails-i18n) を参照してください。) 
* **複数形キー。** CLI は翻訳元に存在する複数形キーのみを翻訳します。そのため、英語の `one`/`other` を翻訳元とするロシア語ファイルには `one` と `other` しか含まれません。rails-i18n を読み込んだ状態で `i18n-tasks missing` を実行し、追加が必要な `few` と `many` のキーを確認してください。
* **引用符なしの `yes`、`no`、`on`、`off`。** General Translation は YAML 1.2 の規則で解析するため、これらは文字列として扱われ、テキストとして翻訳されます。Rails でも通常そうするように、翻訳元ではこれらを引用符で囲んでください。
* **ライブラリ固有の構文。** ICU メッセージなどのカスタム文字列構文は `i18next` と `next-intl` でサポートされています。その他のライブラリを使う場合は、初回の実行後にカスタム構文を含む文字列を確認してください。

「Save」のような短い文字列の意味を明確にするには、対応ファイルとして `.metadata.yaml` を追加し、キーごとに `context` のメモや `maxChars` の上限を指定します ([キーごとのメタデータ](/docs/cli/reference/formats/yaml-files#metadata)) 。[コンテキストグループ](/docs/platform/dashboard/guides/defining-context-for-translations)で用語集とカスタムプロンプトを設定すると、YAML カタログ全体だけでなく、グループ内の他のすべてのプロジェクトでも製品用語を統一できます。また、レビュー担当者は[ダッシュボードで翻訳を編集](/docs/platform/dashboard/guides/reviewing-translations)できます。翻訳済みファイルをローカルで編集した場合は、上書きされないよう、次回の実行前に [`npx gt save-local`](/docs/cli/reference/commands/save-local) を実行してください。

実行後は毎回、アプリと同じ方法でファイルを読み込んで確認します。Rails では `i18n-tasks missing` と `i18n-tasks check-consistent-interpolations`、Symfony では `lint:translations`、Hugo ではビルドで確認できます。 (Symfony のセットアップについては [General Translation vs. Symfony Translation](/kb/general-translation-vs-symfony-translation) を、カタログが JSON の場合は [How do I translate i18n JSON files?](/kb/translate-json-files) を参照してください。)

## よくある質問

### YAML のロケールファイルでは、すべての値を引用符で囲むべきですか？

すべての値を引用符で囲んでおくのが最も安全です。ダブルクォートで囲んだ値は常に文字列として扱われるため、コロン、先頭の `%{name}`、`No` のような単語が含まれていても、翻訳前後のどちらでもファイルの解析結果は変わりません。

### 翻訳したはずの言語なのに、Rails アプリで「translation missing」と表示されるのはなぜですか？

まず、ファイルのトップレベルキーを確認してください。ルートが `en:` のままのファイルは英語として読み込まれるため、新しいロケールにはキーが存在しないことになります。あわせて、そのロケールが `config.i18n.available_locales` に含まれているかも確認してください。

### ロケールファイルでアンカーとエイリアスを使用できますか？

Rails では読み込まれますが、vue-i18n 向けの unplugin-vue-i18n など、対応していないローダーもあります。また、アンカーを付けた値を翻訳すると、それを参照するすべてのエイリアスにも反映されます。そのため、どこでも同じ内容にすべきテキストに限って使用してください。

## 重要なポイント

* 翻訳するのは値のみです。キー、`%{name}` や `{{name}}` などのプレースホルダー、ブロックのインデントはそのまま残します。
* コロンを含む値、`%` または `{` で始まる値、`yes`・`no`・`on`・`off` などの語は引用符で囲みます。引用符がないと、Ruby はこれらを真偽値として解釈します。
* ロシア語とポーランド語では、英語の翻訳元にはない `few` と `many` のキーが必要です。これらがないと、Rails は何も通知せずに `other` へフォールバックします。
* Rails のファイルには、それぞれ固有のロケールルートが必要です。`en:` をルートにしたスペイン語ファイルは、英語として読み込まれます。
* General Translation の CLI では、`"yaml": { "include": [...] }` と [`npx gt translate`](/docs/cli/reference/commands/translate) を使って YAML の文字列値を翻訳でき、キー、コメント、アンカーは保持されます。ただし、Rails のルートや不足している複数形キーへの対応は、引き続きご自身で行う必要があります。

## Related questions

- [General Translation と Rails I18n：両方必要か？](https://generaltranslation.com/ja/kb/general-translation-vs-rails-i18n.mdx): Rails I18n はメッセージの検索と、日付や数値の書式設定を担います。General Translation は翻訳を生成し、英語の変更に合わせて翻訳を常に最新の状態に保つほか、チームでレビューできるダッシュボードも提供します。両者を組み合わせれば、リリースのたびに翻訳済みの Rails カタログを出荷できます。
- [General Translation と i18n-tasks：どちらを使うべきか？](https://generaltranslation.com/ja/kb/general-translation-vs-i18n-tasks.mdx): i18n-tasks は、Rails I18n の不足キーや未使用キーを検出し、ロケールファイルを整理し、Google Translate、DeepL、OpenAI、Yandex、watsonx を使って不足キーを補完できる Ruby gem です。General Translation は、用語集、カスタムプロンプト、ダッシュボードでのレビューを活用してロケールファイル全体を翻訳します。両者は役割が異なるため、多くのチームにとっては併用も有効です。
- [General Translation と Symfony Translation の比較：どちらを使うべきか](https://generaltranslation.com/ja/kb/general-translation-vs-symfony-translation.mdx): Symfony Translation は PHP と Twig でメッセージをレンダリングします。General Translation は CI で YAML カタログを翻訳し、翻訳元の変更に合わせて常に最新の状態に保つほか、レビュー担当者が翻訳を編集できる ダッシュボード も提供します。Symfony のレンダリングはそのままに、リリースワークフローに自動翻訳を組み込めます。
- [i18n の JSON ファイルを翻訳するには？](https://generaltranslation.com/ja/kb/translate-json-files.mdx): JSON ロケールファイルでは、文字列の値だけを翻訳します。複数形以外のキー、{{name}} などのプレースホルダー、タグは変更せずに残しますが、複数形のキーは言語によって異なる点に注意が必要です。たとえばポーランド語では inbox_few と inbox_many が必要になります。ファイル形式に対応したツールや API を使い、レビューの前に出力をパースして検証してください。
- [POファイルとPOTファイルはどのように翻訳すればよいですか？](https://generaltranslation.com/ja/kb/translate-po-files.mdx): Plural-Formsヘッダーが求める各複数形を含め、すべてのmsgstrを埋めます。msgid、msgctxt、プレースホルダーは変更しないでください。msgfmt --checkを実行すると、ヘッダー、複数形の数、および書式フラグ付きエントリのプレースホルダーを検査できます。空のmsgstrがないかは別途確認してください。General TranslationのCLIは、POTテンプレートから言語ごとに翻訳済みのPOファイルを書き出します。

## Previous and next questions

- Previous question: [Weglot の代替: General Translation と Weglot の比較](https://generaltranslation.com/ja/kb/general-translation-vs-weglot.mdx)
- Next question: [多言語サイトのサイトマップはどのように作成すればよいですか？](https://generaltranslation.com/ja/kb/multilingual-sitemap.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/ja/kb/sitemap.md) for every article.