仕様¶

このページを読まなくてもライブラリは使えます。日常的な使い方はチュートリアルとガイドで説明しています。このページはツール作者向けです。このライブラリが実装する規約は、小さく安定した契約として文書化されています。これにより、抽出器、IDE、型チェッカー、将来のpygettextなど、別の実装も同じ規約を対象として相互運用できます。同じルールをその理由とともに、そして参照実装がそれをどう実行しているかも含めて知りたい場合は、まず動作原理をお読みください。

仕様v1を読む

ひと目で分かるルール¶

msgid は、ソース順のリテラル部分と、補間ごとの {name} トークンを連結したものです。リテラルの波括弧はエスケープされます（{ は {{ になります）。名前は単純なプレースホルダー名でなければなりません。つまり、 str.isidentifier() が真で、Pythonキーワードではない名前です。変換指定とフォーマット指定はmsgidに含めず、アプリケーション側で管理します。

t-string	msgid
`t"Hello {name}"`	`Hello {name}`
`t"Total: {amount:,.2f}"`	`Total: {amount}`
`t"Config {{raw}} is {value}"`	`Config {{raw}} is {value}`
`t"Hello {user.name}"`	拒否 — 単純な名前ではない

翻訳が有効なのは、単独の {name} プレースホルダーだけを含み、必須の名前がすべて1回以上現れ、許可された集合にない名前が存在しない場合です。並べ替えと繰り返しは意図的に制限しません。どちらも対象言語の文法上必要になる場合があります。

複数形では、許可される名前は両分岐の和集合、必須の名前は積集合です。そのため t"One file" と t"{n} files" の組み合わせでは、どちらの翻訳形でも n を利用できますが必須ではありません。対象言語の複数形規則がソース言語と異なっても対応できます。

空のmsgidは検索しません。gettextがカタログのメタデータヘッダー用に予約しているためです。

適合性¶

conformance/v1.json は、同じ文書の機械可読版です。t-stringの静的構造からmsgidへの対応と、msgidとカタログパターンからレンダリング結果または拒否への対応を収録しています。

すべてのケースを再現する実装は、仕様v1に適合します。ケースに含まれるのは、導出されたmsgid、受理・拒否されるパターン、レンダリング結果という仕様で定義された要素だけです。エラーメッセージや例外型には依存しないため、他言語の実装でもそのまま実行できます。

補間はPythonソースではなく、構造として記述します。

{
  "spec": "2.2",
  "name": "format spec stays out of the msgid",
  "source": [
    "Total: ",
    {"expression": "amount", "value": 1234.5, "format_spec": ",.2f"}
  ],
  "msgid": "Total: {amount}"
}

"spec"フィールドは仕様のバージョンではありません。v1.jsonのケースはすべて仕様v1に属します。これはそのケースが検証するSPEC.mdの節を指しており、 "2.2"は§2.2、すなわちプレースホルダートークンを導出する規則と読みます。

リファレンス実装は自身のテストスイートの一部として適合性テストを実行するため、文書とコードのずれを気付かないまま残すことはありません。

バージョニング¶

これは仕様v1です。msgidの導出または翻訳検証に後方互換性のない変更を加える場合は、バージョンを上げ、既存ファイルと並べて新しいconformance/vN.jsonを提供します。導出されるmsgidも受理されるパターンも変えない補足説明では、バージョンを上げません。