---
title: "フォーマット"
description: "verbatra が対応するすべての i18n ファイルフォーマットについて、読み書きの方法と、差分が見やすいように書き込みで保たれる内容を説明します。"
type: "reference"
---
# フォーマット

verbatra が対応するすべての i18n ファイルフォーマットについて、読み書きの方法と、差分が見やすいように書き込みで保たれる内容を説明します。

フォーマットアダプターは、ロケールファイルを 1 つの中立的な形に読み込み、そのフォーマット自身の形で書き戻します。[設定ファイル](https://verbatra.kreitz-webdev.de/ja/docs/config-file.md)の `format` 設定キーに、次のいずれかの ID を設定します。

| `format` | ファイル | プレースホルダー | 複数形 | ターゲットファイルがない場合 | [ネイティブのプレースホルダー構文](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#foreign_placeholder_changed) <AvailableFrom version="0.12.0" /> |
| --- | --- | --- | --- | --- | --- |
| `i18next-json` | i18next JSON（`.json`） | `{{name}}`、`$t(...)` | CLDR のキーのサフィックス | 作成される | `{{name}}` |
| `vue-i18n-json` | vue-i18n JSON（`.json`） | `{name}`、`{0}` | 値の中のパイプ | 作成される | `{name}`、`%{name}`、`${name}` |
| `next-intl-json` | next-intl JSON（`.json`） | ICU の引数とタグ | ICU の `plural`、`selectordinal` | 作成される | `{name}`、`%{name}`、`${name}` |
| `ngx-translate-json` | ngx-translate JSON（`.json`） | `{{name}}` | なし | 作成される | `{{name}}` |
| `xliff` | XLIFF 1.2 と 2.0（`.xlf`、`.xliff`） | インライン要素、`{...}` | なし | 拒否される | `{{name}}`、`{name}`、`%{name}`、`${name}` |
| `yaml` | YAML（`.yml`、`.yaml`） | `{{name}}` | なし | 作成される | `{{name}}` |
| `arb` | Flutter ARB（`.arb`） | ICU の引数とタグ | ICU の `plural`、`selectordinal` | 作成される | `{name}`、`%{name}`、`${name}` |
| `properties` | Java/Spring properties（`.properties`） | MessageFormat `{0}`、`{count}` | なし | 作成される | `{name}`、`%{name}`、`${name}` |
| `apple-strings` | Apple `.strings`（`.stringsdict` 付き） | printf `%@`、`%d` | `.stringsdict` のカテゴリ | 作成される | printf `%s` |
| `apple-xcstrings` | Xcode String Catalogs（`.xcstrings`） | printf `%@`、`%lld` | `variations.plural` | 拒否される | printf `%s` |
| `android-xml` | Android `strings.xml` | printf `%s`、`%1$s` | `<plurals>` の quantity | 作成される | printf `%s` |
| `gettext-po` | gettext（`.po`、`.pot`） | printf、`%(name)s` | `msgstr[n]` | 作成される | printf `%s`、`%(name)s` |
| `ini` | INI（`.ini`） | `{name}`、`{0}` | なし | 作成される | `{name}`、`%{name}`、`${name}` |
| `resx` | .NET リソース（`.resx`） | 複合書式 `{0}`、`{1:C}`、名前付き `{name}` | なし | 作成される | `{{name}}`、`{name}`、`%{name}`、`${name}` |

[翻訳の安全性](https://verbatra.kreitz-webdev.de/ja/docs/translation-safety.md)の整合性チェックがどのプレースホルダーを比較するかは、フォーマットによって決まります。

## 4 つの JSON フォーマット [#4-つの-json-フォーマット]

4 つとも、文字列のリーフを持つネストした JSON オブジェクトを読み込みます。

### i18next-json [#i18next-json]

`{{double-brace}}` 補間を使います。複数形は CLDR のキーのサフィックス（`_zero`、`_one`、`_two`、`_few`、`_many`、`_other`）から決まります。`$t(common.foo)` や `$t(common.foo, { options })` のようなネストした参照は、プレースホルダーとして保護されます。認識されるのはデフォルトの `$t(` プレフィックスだけで、options の中に入れ子のかっこがない場合に限ります。

### vue-i18n-json [#vue-i18n-json]

一重波かっこの `{name}` と `{0}` を使い、名前には任意の文字体系を使えます（`{número}`）。

### next-intl-json [#next-intl-json]

値は ICU MessageFormat です。引数名とリッチテキストのタグ名がプレースホルダーで、ICU の本文はそのまま保たれます。ただし各 `plural` と `selectordinal` には、[ターゲット言語ごとの複数形の分岐](https://verbatra.kreitz-webdev.de/ja/docs/translation-safety.md#ターゲット言語ごとの複数形の分岐)にある CLDR の分岐が付きます。ICU として解析できない値は無効として報告され、スキップされます。

### ngx-translate-json [#ngx-translate-json]

`{{double-brace}}` 補間を使い、ネストした参照、複数形、ICU はありません。ファイルはフラット（ドット付きキー）でもネストでもよく、書き込み時にそれぞれのスタイルが保たれます。新しいターゲットはネストで書き込まれます。

### 一重波かっこの捏造ガード [#一重波かっこの捏造ガード]

<AvailableFrom version="0.9.0" />

`i18next-json`、`ngx-translate-json`、`yaml` では、`{name}` はリテラルのテキストなので、訳文で言い換えられます。ただし、ソースにまったく現れなかった `{name}` は、捏造として拒否されます。ガードされるのはこの方向だけです。一重波かっこのカスタムの `interpolation.prefix` と `suffix` を使っている場合、削除されたプレースホルダーは検出されません。

## 名前空間のレイアウト [#名前空間のレイアウト]

[`files.pattern`](https://verbatra.kreitz-webdev.de/ja/docs/config-file.md#ロケールとファイル) はリテラルのパスで、glob ではありません。`public/locales/{locale}/*.json` は `*.json` という名前のファイルを探し、`SOURCE_UNREADABLE` で失敗します。名前空間が 1 つなら、設定したとおりに動作します。

```ts title="verbatra.config.ts"
files: {
  pattern: "public/locales/{locale}/common.json",
},
```

### 名前空間ごとに 1 つの設定 [#名前空間ごとに-1-つの設定]

複数の名前空間がある場合は、名前空間ごとに設定を 1 つ書き、順番に実行します。

```bash
verbatra translate --config verbatra.common.config.ts
verbatra translate --config verbatra.auth.config.ts
```

<Callout type="warn" title="変更検出が保たれるのは最後に実行した名前空間だけ">
同じディレクトリにあるすべての設定が `verbatra.lock.json` を共有し、実行のたびにロケールのベースラインがその設定のキーで置き換わります。そのため、先に実行した名前空間の編集済み文字列は同期している状態として扱われ、翻訳し直されません。翻訳し直すには、キー（またはターゲットファイル）を削除して、欠落として扱われるようにします。
</Callout>

## XLIFF [#xliff]

XLIFF 1.2（`file/body/trans-unit`）と 2.0（`file/unit/segment`）で、翻訳単位のフラットなリストです。

- **キー**：翻訳単位の `id`、次に `resname`、最後に翻訳単位が移動するとずれる位置の順で使います。そのため、すべての翻訳単位に `id` を付けてください。2.0 でセグメントが複数ある翻訳単位は、`<id>#<n>` のキーになります。重複したキーは `INVALID_STRUCTURE` で失敗します。
- **ソースか訳文か**：ドキュメントがソースになるのは、ロケールが `source-language`（2.0 では `srcLang`。地域なしの言語コードは、その地域バリアントにも一致します）に一致し、かつそのロケールをターゲットとして宣言していない場合です。それ以外は訳文です。ただし、どちらの言語も宣言していないドキュメントは、`<target>` を含まなければソースになります。ソースと同じ言語のターゲット（`en` から `en-GB`）は、`target-language`（`trgLang`）を宣言する必要があります。
- **欠落した値**：`<target>` が存在しない、空である、または 1.2 で `state="new"` か `"needs-translation"` が付いている場合は欠落です。2.0 で `state="initial"` のセグメントにあり、ソースと同じ値のターゲットも欠落です。`<source>` のテキストがコピーされることはありません。
- **その場で書き込む**：各値は対応する `<target>` に書き込まれ、なければ `<source>` の後ろに作成されます。1.2 の `new` や `needs-translation`、2.0 の `initial` の状態（`subState` を含む）は `translated` になります。`<source>`、属性、`<note>` は変更されません。
- **欠落した翻訳単位の追加**：ソースの翻訳単位のコピー（ターゲットと 1.2 の `<alt-trans>` は除く）として、対応する `<file>` に追加されます。書き込み先の翻訳単位がない値があると、書き込みはキーを示した `INVALID_STRUCTURE` で失敗します。ソースが読めない場合は、キーを示さずに失敗します。`verbatra extract` は `<source>` だけを持つソースの翻訳単位を追加します。2.0 ではキーが有効な NMTOKEN である必要があります（`u1#0` は拒否されます）。
- **インラインマークアップ**：1.2 の `g`、`x`、`bx`、`ex`、`bpt`、`ept`、`ph`、`it`、`mrk`、2.0 の `ph`、`pc`、`sc`、`ec`、`mrk`、`sm`、`em`、`cp`、および `{...}` の連なりは、どちらのバージョンでも保護されるプレースホルダーです。書き込み時にマークアップのまま残るのはこれらだけです（1.2 の `bpt`、`ept`、`ph`、`it` の中の `<sub>` も含みます）。それ以外、たとえば `<b>` はテキストになります。
- **エスケープ**：テキストはテキストとして読み込まれ（`A &amp; B` は `A & B`）、書き込み時に 1 回だけエスケープされます。許可された要素と完全に一致するテキスト（`&lt;x id="1"/&gt;` など）は、その要素として書き込まれます。`<!DOCTYPE` と `<!ENTITY` はテキストとして書き込まれます。
- **注記**（2.0 では翻訳単位の `<notes>`）は、読み取り専用のコンテキストです（[Excel や CSV で受け渡す](https://verbatra.kreitz-webdev.de/ja/docs/manual-translation.md)を参照）。
- **拒否される入力**：DTD やエンティティ宣言を含むドキュメントは、`INVALID_XML` で失敗します。

## YAML [#yaml]

JSON フォーマットと同じネストしたツリーで、i18next の `{{double-brace}}` 補間と[一重波かっこの捏造ガード](#一重波かっこの捏造ガード)を備え、拡張子で検出されます。コメントは保持されません。文字列以外のスカラーのキーは文字列になります（`1:` は `"1"` として読み込まれます）。マップやシーケンスをキーに使うと `INVALID_STRUCTURE` で、構文が不正だと `INVALID_YAML` で失敗します。エイリアスの展開には上限があります。

## ARB [#arb]

Flutter の `.arb` です。`@key` メタデータと `@@` のグローバルを持つ、メッセージのフラットなオブジェクトです。

- **メッセージは ICU です**：`next-intl-json` とまったく同じように扱われます。
- **メタデータ**：翻訳されず、その場でマージして書き戻されます。既存のターゲットが壊れていると、書き込みは失敗します。`@key.description` は読み取り専用のコンテキストです。
- **書き込みには、そのメッセージだけが含まれます**：除外されたメッセージ（削除されたもの、またはレビューで却下されたもの）は、その `@key` ブロックとともに削除されます。`@@` のグローバルは残ります。
- **`@@locale` は先頭に置かれます**：作成されるターゲットは、`gen-l10n` の表記（`pt_BR`）で `@@locale` を先頭に持ちます。既存のターゲットにある `@@locale` は、値を保ったまま先頭に移動します。既存のターゲットに `@@locale` がない場合は、追加されません。ファイル名と食い違う値は手で直してください。直さないと `flutter gen-l10n` が失敗します。

## Properties [#properties]

Java と Spring の `.properties` です。キーと値のフラットな行で、キーはそのまま保たれます。

- **構文**：`java.util.Properties` に従います（区切り文字、コメント、継続行、エスケープ）。ファイルは UTF-8 として読み込まれ、非 ASCII 文字は `\uXXXX` で書き込まれます。
- **書き込みで保たれるもの**：キーの順序、コメント、空行。既存の各エントリは `key=value` として再生成され（区切り文字、スペース、継続行は保たれません）、新しいキーはソースの順序で追加されます。重複したキーは、最初の位置と最後の値を保ちます。
- **改行コードはファイルに従います**：CRLF が 1 つでもあればすべて CRLF、CR のみならそのまま CR、それ以外は LF です。
- **プレースホルダーは `java.text.MessageFormat` です**：`{0}`、`{0,number}`、`{count}`（名前は任意の文字体系）と、`plural`、`select`、`selectordinal`、`choice` の引数です。シングルクォートによるクォートは解釈されないため、`'{0}'` もプレースホルダーとして数えられます。

## Apple .strings [#apple-strings]

<AvailableFrom version="0.10.0" />

`"key" = "value";` の文で構成されます。複数形は、同じディレクトリで同じベース名の `.stringsdict` にあり、2 つを合わせて読み書きします。

- **UTF-8 のみ**：UTF-16 のファイルは `INVALID_STRUCTURE` で失敗します。UTF-8 で保存し直してください。
- **コメント**：エントリの前の `/* ... */` コメントは、読み取り専用のコンテキストです。`//` コメントは保たれます。`\"`、`\\`、`\n`、`\t`、`\U` のエスケープはデコードされ、それ以外は `INVALID_STRUCTURE` で失敗します。書き込み時にエスケープされるのは、引用符、バックスラッシュ、改行、タブだけです。
- **書き込みで保たれるもの**：順序、コメント、空行。削除されたキーは、そのキー自身のコメントとともに削除されます。ターゲットがなければ、`.lproj` ディレクトリと `.stringsdict` を含めて作成されます。
- **プレースホルダーは printf です**：`%@`、`%d`、`%1$@`、`%%`。フラグ、幅、長さは装飾として扱われます。位置指定の並べ替えは受け入れられます。単独の `%`（`"50% off"`）はプレースホルダーではありません。
- **複数形**：`.stringsdict` の各カテゴリは `<key>_<category>`（`photo_count_one`）になり、ロケールにあるカテゴリだけが往復します。エラーにはファイルとキーが示されます。既存キーのフォーマットキー、変数名、値の型は、書き直しても残ります。新しいキーには `%#@<key>@`、変数名としてのキー、型 `d` が付きます。
- **レイアウト**：`{locale}.lproj/Localizable.strings` に、特別なロケール表記は不要です。

## Xcode String Catalogs (.xcstrings) [#xcode-string-catalogs-xcstrings]

<AvailableFrom version="0.10.0" />

すべてのロケールを 1 つに収めた JSON カタログです。Xcode 15 で `.strings` の後継となりました。

- **全ロケールで 1 つのファイル**：`files.pattern` には引き続き `{locale}` が必要ですが、`{locale}` は空文字列に展開されるため、すべてのロケールが同じファイルに解決されます（`{locale}Localizable.xcstrings` は `Localizable.xcstrings` です）。すべてのライターがこのファイルで直列化されるため、`--concurrency` を指定してもロケールは 1 つずつ実行されます。
- **キー**：`sourceLanguage` のローカライズがないキーは、キーのテキストをソースとして使います。ターゲットのローカライズがない場合は、未翻訳として数えられます。
- **複数形**（`variations.plural` 以下）は `<key>_<category>` になり、存在するカテゴリだけが対象です。
- **プレースホルダーは printf です**：`.strings` と同じで、`%lld` は `%d` と同じ扱いです。
- **`shouldTranslate: false`** のキーは、送信も変更もされません。
- **書き込みはドキュメントにパッチを当てます**：新しい値を持つローカライズは、`state: "translated"` を付けて丸ごと書き直されます。その中のほかのフィールド（デバイスのバリエーション、置換）は削除されます。残りは意味的に同一のままですが、ファイルは 2 スペースの JSON として再シリアライズされます。カタログはあらかじめ存在している必要があります。先に Xcode で作成してください。
- **エラー**：ファイル、キー、ロケールが示されます。

## Android strings.xml [#android-stringsxml]

<AvailableFrom version="0.10.0" />

ソースは `res/values/strings.xml`、ターゲットごとのファイルは `res/values-<qualifier>/strings.xml` です。`files.localeStyle: "android"` を設定します（[設定ファイル](https://verbatra.kreitz-webdev.de/ja/docs/config-file.md#ロケールとファイル)）。

- **エントリ**：`<string name>` が 1 つのエントリです。`<plurals>` は `<item>` ごとに `key[quantity]` になり、存在する quantity だけが対象です。
- **スキップされるもの**：`translatable="false"` のリソース、`<string-array>`、インライン要素（`<b>`、`<xliff:g>`、CDATA）を含む `<string>` は、そのまま保たれます。`formatted="false"` は通常どおり翻訳されます。
- **エスケープ**：`\'`、`\"`、`\n`、`\t`、先頭の `\@` や `\?` はデコードされ、書き込み時に再びエスケープされます。
- **プレースホルダーは printf です**：`%s`、`%d`、`%1$s`、`%%`。単独の `%` はプレースホルダーではありません。
- **書き込み**：ファイルにパッチを当て、削除されたキーを取り除き、ファイルがなければディレクトリごと作成します。
- **制限**：翻訳済みのキーが、のちにソース側で翻訳対象外のエントリになると、ターゲットから削除されます。`--prune` は複数形の quantity を認識しないため、ターゲットにしかない quantity を削除することがあります。
- **エラー**：`<resources>` 以外のルート、無効な名前や quantity、重複したキーが、エラーとして示されます。DTD やエンティティは拒否されます。

## gettext .po/.pot [#gettext-popot]

<AvailableFrom version="0.10.0" />

`msgid` と `msgstr` のエントリです。

- **`msgctxt`** は `msgid` と U+E000 で連結され、1 つのキーになります。この文字を含むソースは拒否されます。
- **複数形**は、CLDR のカテゴリではなく、インデックスをキーにした `key[n]` です。`Plural-Forms` はそのまま保たれ、インデックスの範囲を決めるのは `nplurals` だけです。`Plural-Forms` がない複数形エントリは、`msgfmt --check` と同様に拒否されます。
- **フラグとコメント**：`#, fuzzy` の値は現在の値として読み込まれ、フラグは保たれます。`#.` コメントは読み取り専用のコンテキストです。`#:` とそのほかのフラグは保たれ、`#~` ブロックは何も影響せずに残り、ヘッダーには一切触れません。`msgstr` が空の `.pot` は問題なく読み込めます。ただしソースカタログでは各 `msgstr` が翻訳対象のテキストなので、空のものは [`SOURCE_VALUE_EMPTY`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#source_value_empty) でスキップされます。
- **ターゲットがない場合**は、最小限のヘッダーで作成されます。複数形がある場合は、最大のインデックスに合わせた `Plural-Forms` が付きます（正確な文法が必要なら、実際のテンプレートから始めてください）。
- **プレースホルダーは printf です**：`%(name)s` を含みます。長さ修飾子（`%ld`）は認識されません。
- **エラー**：`msgid` と行が示されます。`--prune` は複数形のインデックスを認識しないため、ターゲットにしかない形を削除することがあります。

## INI [#ini]

<AvailableFrom version="0.11.0" />

`key=value` の行の上に、`[section]` ヘッダーが 1 階層あります。

- **キー**：`[home]` の中のキーは `home.title` の形になります。最初のセクションより前のキーは名前のままで、リテラルのドットはエスケープされます。
- **書き込み**：値だけを変更し、表記、スペース、コメント、空行は保たれます。新しいキーはセクションの末尾に、新しいセクションはファイルの末尾に追加されます。
- **値**：二重引用符で囲まれた値は引用符が外され、`\\`、`\"`、`\n`、`\r`、`\t` がデコードされます。必要な値は、引用符付きで書き込まれます。行内の `;` は値の一部です。
- **プレースホルダー**は `{name}` と `{0}` で、名前は任意の文字体系です。複数形はありません。
- **エラー**：ヘッダーが不正だと `AdapterError` をスローします。`=` のない行はそのまま保たれます。

## .NET .resx [#net-resx]

<AvailableFrom version="0.11.0" />

`<root>` の下の `<data name><value>` 要素です。このアダプターが引き受けるのは `.resx` ファイルだけです。

- **書き込みは値だけにパッチを当てます**：それ以外は変わりません。バイトオーダーマークは取り除かれ、新しい `<data>` 要素、または値の前後に空白がある要素には `xml:space="preserve"` が付きます。
- **翻訳されないもの**：`type` または `mimetype` を持つ `<data>`、`>>` または `$` で始まる名前は、そのまま保たれます。`<comment>` は読み取り専用のコンテキストです。
- **プレースホルダー**は、複合書式項目と名前付き項目を丸ごと扱います（`{0}`、`{1,-10}`、`{2:C}`、`{when:d}`）。そのため、名前を変えた項目は拒否されます。`{{`、`}}`、余分な波かっこも保護されます。ICU のチェックはなく、複数形もありません。
- **ターゲットがない場合**は、標準のヘッダーで作成されます。
- **拒否されるキー**：ターゲットが型付き、デザイナー、マークアップのエントリとして持っている値や、読み戻せなかったキーがあると、書き込みはそのキーを示す `AdapterError` で失敗します。
- **エラー**：無効な XML、`<root>` 以外のルート、DTD やエンティティは拒否されます。

## ドキュメント内のキーの順序 [#ドキュメント内のキーの順序]

JSON フォーマット、YAML、ARB はドキュメントの順序を保ちます。`"404"` のような整数に見えるキーは先頭に移されず、新しいキーはソースの順序で追加され、ARB のメタデータは位置を保ちます。XLIFF の順序は変わりません。

## ドット付きキーと衝突 [#ドット付きキーと衝突]

`ngx-translate-json` は、ドット付きキーをネストしたパスとして読み込みます。ほかのツリーフォーマット（JSON 系、YAML、ARB）は、`"foo.bar"` のようなリテラルのドット付きリーフを、書かれたままに保ちます。同じパスを両方の書き方で書くと（`"foo.bar"` と `"foo": { "bar": ... }` を並べると）、`INVALID_STRUCTURE` で失敗します。`ngx-translate-json` では、ネストしたオブジェクトと並ぶフラットなドット付きキーと、ネストしたオブジェクト内のドット付きキーの場合に、`MIXED_STRUCTURE` で失敗します。

## ファイルの読み書き [#ファイルの読み書き]

- **上限**：入力サイズとネストの深さには上限があります（`INPUT_TOO_LARGE`、`MAX_DEPTH_EXCEEDED`）。
- **アトミックな書き込み**：一時ファイルを名前変更して置き換えるため、書きかけのファイルが残ることはありません。
- **レイアウト**：XML フォーマットは改行コードと末尾の改行を保ち、新しい要素は隣の要素に合わせてインデントします。新しい gettext エントリは空行の後に置かれ、作成された `.po` は `Language` にロケールを書きます（`pt_BR`）。
- **文字列以外のリーフ**：JSON フォーマット、YAML、ARB では、数値、真偽値、null のリーフは受け入れられますが翻訳されず、書き直すと削除されます。配列は `INVALID_STRUCTURE` で失敗します。
- **エラー**は構造化されていて、シークレットを含みません。[フォーマットアダプターのエラーコード](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#adapter-error-codes)を参照してください。

## verbatra 外部のフォーマット [#verbatra-外部のフォーマット]

<AvailableFrom version="0.11.0" />

別のフォーマットは、`custom:toml` のような `custom:` ID を持つ独自のアダプターで追加できます。SDK を通して、信頼されたコードとして実行されます。詳しくは[カスタムフォーマットアダプターを書く](https://verbatra.kreitz-webdev.de/ja/docs/custom-format-adapters.md)を参照してください。

## 値に含まれるインラインマークアップ [#値に含まれるインラインマークアップ]

<AvailableFrom version="0.11.0" />

[インラインマークアップの一致](https://verbatra.kreitz-webdev.de/ja/docs/translation-safety.md#インラインマークアップの一致)のチェックは、すべてのフォーマットでタグごとに適用されます。

- `xliff` は、独自のインライン要素をプレースホルダーとして保護します。`<b>` などのほかの HTML は、マークアップとして比較されます。
- `next-intl-json` と `arb` は、対になった `<b>...</b>` をプレースホルダーとして扱い、自己終了の `<br/>` をマークアップとして比較します。属性を持つタグは無効な ICU として拒否されます。
- `android-xml` はデコード後の値を比較するため、`&lt;b&gt;` は `<b>` です。
- ほかのフォーマットにはマークアップの概念がないため、このチェックだけがマークアップを検出します。
