リファレンス / 設定
機械翻訳されたページ
フォーマット
verbatra が対応するすべての i18n ファイルフォーマットについて、読み書きの方法と、差分が見やすいように書き込みで保たれる内容を説明します。
フォーマットアダプターは、ロケールファイルを 1 つの中立的な形に読み込み、そのフォーマット自身の形で書き戻します。設定ファイルの format 設定キーに、次のいずれかの ID を設定します。
format | ファイル | プレースホルダー | 複数形 | ターゲットファイルがない場合 | ネイティブのプレースホルダー構文 |
|---|---|---|---|---|---|
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} |
翻訳の安全性の整合性チェックがどのプレースホルダーを比較するかは、フォーマットによって決まります。
4 つの JSON フォーマット
4 つとも、文字列のリーフを持つネストした JSON オブジェクトを読み込みます。
i18next-json
{{double-brace}} 補間を使います。複数形は CLDR のキーのサフィックス(_、_、_、_、_、_)から決まります。$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_ で失敗します。名前空間が 1 つなら、設定したとおりに動作します。
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 & BはA & B)、書き込み時に 1 回だけエスケープされます。許可された要素と完全に一致するテキスト(<x id="1"/>など)は、その要素として書き込まれます。<!DOCTYPEと<!ENTITYはテキストとして書き込まれます。 - 注記(2.0 では翻訳単位の
<notes>)は、読み取り専用のコンテキストです(Excel や CSV で受け渡すを参照)。 - 拒否される入力:DTD やエンティティ宣言を含むドキュメントは、
INVALID_で失敗します。XML
YAML
JSON フォーマットと同じネストしたツリーで、i18next の {{double-brace}} 補間と一重波かっこの捏造ガードを備え、拡張子で検出されます。コメントは保持されません。文字列以外のスカラーのキーは文字列になります(1: は "1" として読み込まれます)。マップやシーケンスをキーに使うと INVALID_ で、構文が不正だと INVALID_ で失敗します。エイリアスの展開には上限があります。
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_で失敗します。UTF-8 で保存し直してください。STRUCTURE - コメント:エントリの前の
/* ... */コメントは、読み取り専用のコンテキストです。//コメントは保たれます。\"、\\、\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_ で失敗します。ngx-translate-json では、ネストしたオブジェクトと並ぶフラットなドット付きキーと、ネストしたオブジェクト内のドット付きキーの場合に、MIXED_ で失敗します。
ファイルの読み書き
- 上限:入力サイズとネストの深さには上限があります(
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はデコード後の値を比較するため、<b>は<b>です。- ほかのフォーマットにはマークアップの概念がないため、このチェックだけがマークアップを検出します。