本文へスキップ
本文へスキップ

リファレンス / 設定

機械翻訳されたページ

このページは自動翻訳のため、誤りや不自然な表現が含まれている可能性があります。正式な内容は英語版です。英語の原文を読む。

フォーマット

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

フォーマットアダプターは、ロケールファイルを 1 つの中立的な形に読み込み、そのフォーマット自身の形で書き戻します。設定ファイルの format 設定キーに、次のいずれかの ID を設定します。

formatファイルプレースホルダー複数形ターゲットファイルがない場合ネイティブのプレースホルダー構文
i18next-jsoni18next JSON(.json){{name}}、$t(...)CLDR のキーのサフィックス作成される{{name}}
vue-i18n-jsonvue-i18n JSON(.json){name}、{0}値の中のパイプ作成される{name}、%{name}、${name}
next-intl-jsonnext-intl JSON(.json)ICU の引数とタグICU の plural、selectordinal作成される{name}、%{name}、${name}
ngx-translate-jsonngx-translate JSON(.json){{name}}なし作成される{{name}}
xliffXLIFF 1.2 と 2.0(.xlf、.xliff)インライン要素、{...}なし拒否される{{name}}、{name}、%{name}、${name}
yamlYAML(.yml、.yaml){{name}}なし作成される{{name}}
arbFlutter ARB(.arb)ICU の引数とタグICU の plural、selectordinal作成される{name}、%{name}、${name}
propertiesJava/Spring properties(.properties)MessageFormat {0}、{count}なし作成される{name}、%{name}、${name}
apple-stringsApple .strings(.stringsdict 付き)printf %@、%d.stringsdict のカテゴリ作成されるprintf %s
apple-xcstringsXcode String Catalogs(.xcstrings)printf %@、%lldvariations.plural拒否されるprintf %s
android-xmlAndroid strings.xmlprintf %s、%1$s<plurals> の quantity作成されるprintf %s
gettext-pogettext(.po、.pot)printf、%(name)smsgstr[n]作成されるprintf %s、%(name)s
iniINI(.ini){name}、{0}なし作成される{name}、%{name}、${name}
resx.NET リソース(.resx)複合書式 {0}、{1:C}、名前付き {name}なし作成される{{name}}、{name}、%{name}、${name}

翻訳の安全性の整合性チェックがどのプレースホルダーを比較するかは、フォーマットによって決まります。

4 つの JSON フォーマット

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

i18next-json

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

vue-i18n-json

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

next-intl-json

値は ICU MessageFormat です。引数名とリッチテキストのタグ名がプレースホルダーで、ICU の本文はそのまま保たれます。ただし各 plural と selectordinal には、ターゲット言語ごとの複数形の分岐にある CLDR の分岐が付きます。ICU として解析できない値は無効として報告され、スキップされます。

ngx-translate-json

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

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

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

名前空間のレイアウト

files.pattern はリテラルのパスで、glob ではありません。public/locales/{locale}/*.json は *.json という名前のファイルを探し、SOURCE_UNREADABLE で失敗します。名前空間が 1 つなら、設定したとおりに動作します。

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

名前空間ごとに 1 つの設定

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

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

変更検出が保たれるのは最後に実行した名前空間だけ

同じディレクトリにあるすべての設定が verbatra.lock.json を共有し、実行のたびにロケールのベースラインがその設定のキーで置き換わります。そのため、先に実行した名前空間の編集済み文字列は同期している状態として扱われ、翻訳し直されません。翻訳し直すには、キー(またはターゲットファイル)を削除して、欠落として扱われるようにします。

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 で受け渡すを参照)。
  • 拒否される入力:DTD やエンティティ宣言を含むドキュメントは、INVALID_XML で失敗します。

YAML

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

ARB

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

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

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

"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)

すべてのロケールを 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

ソースは res/values/strings.xml、ターゲットごとのファイルは res/values-<qualifier>/strings.xml です。files.localeStyle: "android" を設定します(設定ファイル)。

  • エントリ:<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

msgid と msgstr のエントリです。

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

INI

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

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

.NET .resx

<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 で失敗します。
  • エラーは構造化されていて、シークレットを含みません。フォーマットアダプターのエラーコードを参照してください。

verbatra 外部のフォーマット

別のフォーマットは、custom:toml のような custom: ID を持つ独自のアダプターで追加できます。SDK を通して、信頼されたコードとして実行されます。詳しくはカスタムフォーマットアダプターを書くを参照してください。

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

インラインマークアップの一致のチェックは、すべてのフォーマットでタグごとに適用されます。

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

このページの内容