Javaプロパティ

Javaの.propertiesリソースバンドルをキーごとに翻訳。コメント、空行、各行のレイアウトはそのまま保持します。

.propertiesファイルは、JavaのResourceBundleやSpringのMessageSourceが読み込む形式で、1行に1件ずつキーとメッセージを対応付けます。propertiesファイルハンドラーは各キーの値を翻訳し、元のファイルのコピーに書き込みます。コメント、空行、キーの順序、区切り文字、空白はそのままです。変更されるのは、翻訳されたキーの値だけです。

プロパティファイルの翻訳を設定する #

プロパティファイルが対象になるのは、パターンが.propertiesで終わり、形式が自動判定されるファイルエントリか、"format": "properties"を設定したファイルエントリだけです。"format": "properties"を指定したエントリでは、.propertiesファイルだけが選択されます。src/main/resources/**/*のような広範囲に一致するパターンでも、この形式を指定しなければプロパティファイルは選択されません。そのため、application.propertiesなどの設定ファイルが誤って翻訳されることはありません。

messages_en.propertiesのようにファイル名にロケールが含まれる場合、各翻訳先ファイルは元のファイルと同じ場所に作成され、ファイル名の同じ位置に翻訳先ロケールが入ります。ロケールはJavaのアンダースコア形式pt_BRで表記され、ResourceBundleがこの形式で検索します。

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "pt-BR"],
  "files": [{ "pattern": "src/main/resources/messages_en.properties" }]
}

これにより、messages_de.propertiesとmessages_pt_BR.propertiesが書き込まれます。地域を含む翻訳元ロケールも同じ方法で検索されます。"sourceLocale": "en-US"の場合、翻訳元はmessages_en_US.propertiesです。別の形式で書き込むには、エントリにlocaleFormatを設定します。たとえば、pt-BRに対して"bcp47"を指定できます。翻訳元が、名前にロケールを含まない既定のバンドルmessages.propertiesの場合は、翻訳先のパスを指定します。

json
{
  "pattern": "src/main/resources/messages.properties",
  "targetPath": "src/main/resources/messages_[locale].properties"
}

同じ設定をCLIとGitHub Appで使用できます。

ファイルの読み込み方法 #

キーと値は、java.util.Propertiesと同じ方法で読み込まれます。

  • 単位。各キーが1つの翻訳単位です。同じキーが2回出現する場合、Javaが読み込む最後の値を使って1回だけ翻訳されます。そのキーが出現するすべての箇所に、同じ翻訳が書き込まれます。
  • 区切り文字。=、:、または空白文字でキーと値を区切ります。=と:の前後には、任意で空白を入れられます。
  • コメントと空行。空白を除いた最初の文字が#または!の行は、コメントとして扱われます。コメントと空行は翻訳に送信されません。
  • 行の継続。\で終わる行は次の行に続き、次の行の先頭にある空白は取り除かれます。複数行にまたがる値は、1行にまとめて書き戻されます。
  • エスケープ。\uXXXX、\t、\n、\r、\f、\=、\:、\ 、\\、その他のエスケープされた文字は、翻訳前にデコードされます。\uエスケープの形式が不正な場合は、Javaと同様にファイルの処理が失敗します。
  • 空の値。値が空、または空白のみのキーはそのまま保持され、翻訳されません。翻訳先の空の値は未翻訳として扱われます。ただし、preservedKeysに含まれるキーでは、空の値がそのまま保持されます。

ファイルはUTF-8として読み込まれます。ISO-8859-1で保存され、アクセント付き文字をエスケープせずに含むファイルには対応していません。UTF-8で保存するか、それらの文字を\uXXXXとして記述してください。ファイル先頭のUTF-8バイトオーダーマークは保持されません。

翻訳の書き込み方法 #

翻訳された各値は、Javaでそのままの内容を読み込めるようにエスケープされます。対象は、バックスラッシュ、改行、タブ、改ページなどの制御文字と、先頭にある空白、=、:です。ASCIIの範囲外の文字は、ファイル内にすでにある値に合わせて書き込まれます。コメントはこの判定に含まれません。

翻訳先ファイルの値(最初の翻訳先が作成される前は翻訳元の値)éや中などの文字の書き込み形式
エスケープされていないUTF-8テキストをすでに含むそのまま
ASCIIのみを含む\u00E9、\u4E2Dの形式

値をエスケープする場合は、書き込むすべての値が対象になります。翻訳元でエスケープされていないテキストを含む値は、ロックや保持の対象であってもエスケープされます。エスケープされたファイルは、UTF-8リーダーでも、ISO-8859-1として読み込むProperties.load(InputStream)でも読み込めます。

{0}、{name}、%sなどのプレースホルダーは、翻訳でも保持されます。JavaのMessageFormatの引用規則は自動では適用されません。たとえば、引数を含むメッセージでアポストロフィを''と記述する処理は、自分で行う必要があります。

キーやテキストを翻訳せずに保持する #

lockedKeys、preservedKeys、ignoredKeysは、従来のCLIと同様にキー全体に対して照合されます。対象になるのは、パターンと完全に一致するキー、パターンの後に.、/、-のいずれかを挟んで文字列が続くキー、またはグロブとして解釈したパターンに一致するキーです。たとえば、appはapp.titleに、app.*はapp.titleとapp.menu.saveに、*.portはserver.portに一致します。$で始まるパターンは、代わりに$["app.title"]のような、キーに対するJSONPathクエリとして扱われます。

オプション翻訳先での結果
lockedKeys翻訳元の値を使用します。翻訳には送信されません。
preservedKeys翻訳先の既存の値を使用します。値がない場合は翻訳元の値を使用します。
ignoredKeys継続行を含め、エントリ全体が除外されます。

lockedPatternsは、値の一部を翻訳せずに保持します。各エントリにはRE2構文の正規表現を指定し、各値の中で一致するすべての部分をロックします。^と$は、値の内部の改行位置にも一致します。

json
{
  "pattern": "src/main/resources/messages_en.properties",
  "lockedPatterns": ["\\{\\{[^}]+\\}\\}"]
}

一致部分は、必ず保持するトークンとしてモデルに送信され、バイト単位でそのまま書き戻されます。一致部分が失われたり変更されたりした翻訳は拒否され、書き込まれません。パターンは各値の内部で照合され、行、キー、コメントをまたいでは一致しません。一致部分を含む値では、{0}や%sなどのプレースホルダーも同じ方法で保護されます。

RE2はテキストの長さに比例する時間で処理するため、先読み・後読み((?=、(?!、(?<=、(?<!)や後方参照(\1、\k<name>)には対応していません。ASCIIの範囲外の文字は、\u00E9ではなく\x{00E9}と記述してください。CLIとGitHub Appは、設定の読み込み時に、正規表現として不正なパターンを拒否します。また、RE2が対応していない構文を使うと、該当するパターンが示され、プッシュが失敗します。lockedPatternsはプロパティファイル専用です。別の形式のエントリに設定すると、そのエントリは拒否されます。

--keyは、lockedKeysと同じ照合方法で、プッシュの対象を指定したキーに絞り込みます。

再利用と修正 #

前回のプッシュ以降、翻訳元の値が変わっていないキーでは、既存の翻訳が保持されます。翻訳元の値が変わると、そのキーは再翻訳されます。翻訳先ファイルにしかないキーは削除され、翻訳先のキーの順序とレイアウトは翻訳元に合わせられます。

--keyを指定してプッシュすると、代わりに既存の翻訳先が編集されます。変更されるのは選択された値だけです。翻訳先にしかないキーやコメントを含め、それ以外の行はそのまま保持されます。選択したキーが翻訳先にない場合は、末尾に追加されます。

翻訳を1つ修正するには、翻訳先ファイルで該当する翻訳を編集します。再生成するには、--keyを指定してもう一度プッシュします。

sh
lingo push --key checkout.title --wait