Macで翻訳のプレースホルダーを検証するには、各引数の位置、型、意図された用途をソースメッセージと比較します。Xcodeの不一致診断を使い、複数形の置換を確認してから、異なるサンプル値を使って表示されたラベルをテストします。

このガイドは、XcodeでMacアプリのローカライズ済みラベルをレビューする人を対象としています。アプリが渡す値と照らし合わせて、1つのメッセージとその翻訳を確認する作業を扱います。以下のラベルはすべて架空の英語の例であり、実際の翻訳ではなく、書式設定の仕組みを示しています。

メッセージの引数コントラクトには何を含めますか？

引数コントラクトとは、メッセージが受け取る値について、その位置、書式の型、意味、想定される用途を記録したレビュー用メモです。Appleの別個のファイル形式ではなく、ソースコードとカタログから作成する実用的なチェックリストです。

SwiftのString.LocalizationValueは、実行時の値を補間するローカライズ可能な文字列をサポートしています。そのドキュメントでは、ソーステキストをローカライズキーとして使う方法と、別のキーおよびデフォルト値を指定する方法も区別しています。そのため、識別子だけではメッセージの引数がわからないことがあります。デフォルトのソーステキストと呼び出し箇所を確認してください。String.LocalizationValue

書式文字列Added %lld items to %@を考えてみましょう。この例では、アプリが整数の個数に続けて、オブジェクトであるコレクションのラベルを渡します。翻訳を編集する前に、次のようにコントラクトを書き留めます。

引数の位置 意味 想定される書式 例の値
1 追加された項目の数 %lld 7
2 移動先コレクションのラベル %@ Canvas

Appleの書式リファレンスでは、%@はオブジェクト変換、%dは符号付き32ビット整数、%fはdouble変換、llはlong longの整数長修飾子と定義されています。また、%1$@のような位置指定形式も説明されています。型の情報は省略せずに保持してください。%lldを%dに変えると、想定される整数型が変わります。このリファレンスはアーカイブされているため、現在のカタログのドキュメントと併せて書式構文の確認に利用してください。String Format Specifiers

型が同じ場合でも、レビュー記録には引数の意味を加えてください。Moved %@ to %@では、型の確認だけでは項目のラベルと移動先のラベルを区別できません。構文が正しくても、値と語句の対応関係が正しい必要があります。

Xcodeで正しいソースを見つけるには？

まずXcodeでプロジェクトを開き、メッセージが含まれるカタログを特定します。ソースが変更されていたら、Product > Buildを選んで抽出済み文字列を更新します。Projectナビゲータでカタログを選び、Editor > Assistantを選択して、メッセージキーを選ぶとソースを表示できます。Appleは、カタログの項目を見つけて更新するこの手順を説明しています。Localizing and varying text with a string catalog

呼び出し箇所で実際にどの値が、どの順序で、どのローカライズAPIを通じて渡されるかを確認します。AppleはString(localized:)のようなローカライズ可能なAPIを推奨しています。別個のdefaultValueを指定するイニシャライザでは、最初のパラメーターがキー、2番目のパラメーターがデフォルトのソース文字列になります。これは、collection.added.summaryのような中立的な識別子がメッセージを持つ場合に重要です。Preparing your app’s text for translation

カタログとキー、デフォルトのソース文言、順序付きの引数の意味と型をまとめて記録します。これらが一致しない場合は、翻訳を調整する前に食い違いを解消してください。そうしないと、アプリが現在渡す値ではなく、古いソースに翻訳を合わせてしまうおそれがあります。

今後の編集に備えて、コンテキストも記録しておきましょう。Appleはローカライズ可能な文字列にコメントを付ける機能をサポートしています。たとえば、引数1は項目数、引数2は移動先コレクションのラベルだと説明する架空のコメントが役立ちます。書式指定子では表せない情報をローカライズ担当者に伝えられます。Preparing your app’s text for translation

個数、型、引数の位置を確認するには？

AppleはString Catalogの検証機能を導入し、書式指定子の不一致などの一般的な問題を検出できるようにしました。一部の問題には修正案も表示されます。その項目についてXcodeが表示する診断を確認してください。提示された修正は構文上の修正案として扱い、メッセージの意味が保たれていることを検証します。Build multilingual-ready apps

複数形の置換を含まない単純なメッセージでは、次の順序でレビューします。

  1. ソースと候補テキストに含まれる、引数を使うプレースホルダーをすべて特定します。
  2. 各プレースホルダーを引数の位置に対応付けます。
  3. 完全な書式型をコントラクトと比較します。
  4. 必要な値が、文言の意図する位置にすべて現れることを確認します。
  5. 追加、省略、繰り返しがある場合は、1つずつ調べます。

位置指定表記を使うと、引数の対応関係を保ったまま翻訳の語順を変えられます。%2$@: added %1$lld itemsでは、最初に表示されるプレースホルダーが引数2、次が引数1を参照します。Appleはn$による位置指定構文を説明しています。String Format Specifiers

次の判定表は、上記の2つの引数の例に適用したものです。これはレビュー結果の案であり、Xcodeを実行して得た結果ではありません。

候補の書式テキスト レビュー結果 理由
Added %lld items to %@ 単純なコントラクトに一致 個数が先、移動先が後
%2$@: added %1$lld items 並べ替え後も一致 位置指定により、両方の引数の対応関係が保たれる
Added %d items to %@ 整数型を修正 引数1に想定される長さ修飾子が使われていない
Added %lld items 省略を調査 このメッセージに必要な移動先がない
Added %1$lld items to %1$@ 参照を修正 引数1が矛盾する型で参照されており、引数2がない
Added %1$lld items to %2$@ (%2$@) 繰り返しを確認 出現箇所は3つだが、参照される引数は2つだけ

出現回数と、重複のない引数の数は分けて考えてください。最後の行はその違いを示しています。引数2を繰り返しても、渡される値が3つになるわけではありません。その繰り返しが文言として適切かどうかは、編集上の判断です。この作業では、目的が明らかになるまで確認対象として記録してください。

同様に、パーセント記号をすべて引数として数えないでください。Appleは%%をリテラルのパーセント記号と定義しています。Scale: %lld%%のような書式ラベルには、値のプレースホルダーが1つと、エスケープされたパーセント記号が1つ含まれます。String Format Specifiers

複数形の置換には、なぜ別の確認が必要ですか？

複数形のメッセージでは、値を表示するテキストだけでなく、選択の仕組みも確認する必要があります。AppleはString Catalogに関するセッションで、置換には複数形のケースを収めた辞書を含められると説明しています。インスペクタには、制御する引数の位置とC形式の書式指定子が表示されます。そのため、ある分岐で引数を数値として表示しなくても、その置換が引数に依存する場合があります。Discover String Catalogs

架空の項目数メッセージでは、One item addedと%lld items addedを比べてみましょう。最初の分岐は数量を語句で表し、2つ目は数値として表示します。すべての分岐で表示されるプレースホルダー数が同じでなければならないというルールでは、最初の分岐を不必要に不合格としてしまいます。Appleのドキュメントによると、stringsdictの動作では複数形の形式から数値の書式指定子を省略でき、数字を語句で表す方法も示されています。Stringsdict file format

次のように分岐ごとに確認します。

  • インスペクタで、置換を制御する引数の位置と型を確認します。
  • 対象ローカライズに含まれる複数形の分岐をすべて調べます。
  • 表示されるプレースホルダーを、それが参照する引数と照合します。
  • 数値の表示を省略している場合は、分岐の文言がその理由を説明していることを確認します。
  • ほかのメッセージ引数は個別に確認します。個数を語句で表しても、コレクションのラベルの欠落は説明できません。

独立して変化する2つの個数がある場合は、それぞれの役割を保ちます。項目とコレクションに関する架空のメッセージでは、項目数が項目の置換を制御し、コレクション数がコレクションの置換を制御する必要があります。Appleは1つのメッセージ内に複数の置換を含める方法を説明し、実行時の出力は選択された複数形のケースを組み合わせて生成されると述べています。Discover String Catalogs

Macで修正したメッセージを確認するには？

項目を修正したらアプリをビルドし、カタログに残っている診断を確認します。次に、対象ローカライズで該当画面を実行します。Appleが案内する手順は、Product > Scheme > Edit Schemeを選び、Runを選択してOptionsを開き、App Languageと適切なApp Regionを選び、Closeをクリックして、選択した実行先で実行することです。Testing localizations when running your app

値の入れ替わりがわかるサンプルを選びます。2つの個数引数には、2と7のように異なる数値を使います。2つのテキスト引数には、TileとCanvasのように異なるラベルを使います。これらは例示用のテスト入力です。目的は、渡した値がメッセージのどの部分に表示されるかを見分けることです。

複数形のメッセージでは、確認対象の分岐に到達する値を試します。2つの置換が独立して変化する場合は、片方の個数を固定してもう片方を変える組み合わせも含めます。選択された文言と、表示される各値の位置を確認してください。ある組み合わせで正しく表示されても、ほかの分岐は未確認のままです。

翻訳の状態とコントラクトの確認は分けて記録します。Appleによると、カタログの緑色のチェックマークは、テキスト入力後に翻訳済みであることを示します。その状態表示だけを4項目すべての証拠とせず、実際に確認した内容、すなわち引数の対応付け、型の比較、分岐の確認、表示例を記録してください。Localizing and varying text with a string catalog

プレースホルダーが意図した引数に対応し、型が一致し、分岐ごとの省略や繰り返しに明確な理由があると確認できたら、そのメッセージを次の段階に進められます。簡潔なコントラクトをメッセージのそばに記録しておけば、次回のソースや翻訳の編集を評価しやすくなります。

参考資料