Macアプリの翻訳を往復させるには、Xcode Localization Catalogを書き出し、複数形の構造と引数の対応関係を保ったうえで、返却されたパッケージを読み込んでテストします。このガイドでは、架空の選択ラベルを使って、何を引き渡し、何を確認すべきかを具体的に示します。

この作業は、Mac上のXcodeで翻訳者向けの納品物を準備する人を対象としています。個数に応じて変化するメッセージを1つ翻訳に出し、その挙動を保ったまま戻します。例のラベルは Selected 3 tiles in 2 groups. です。2つの数はそれぞれ独立して変わるため、納品物では読みやすい文言だけでなく、それ以上の情報を保つ必要があります。

書き出す前にメッセージの仕様を定める

メッセージの仕様を小さな仕様書として扱います。アプリがどのエントリを参照するのか、実行時にどの値を渡すのか、どの値が文法上の変化を制御するのかを記録します。Appleの説明によると、String.LocalizationValue は、実行時に渡される値を含め、補間を使ったローカライズ可能な文字列に対応しています。また、識別子を表示されるソーステキストと別にしたい場合に、静的なキーと別個のデフォルト値を使う方法も説明されています。String.LocalizationValue

この例では、翻訳依頼に添えて次の仕様を記録します。これは架空のラベルに関する例示的な要件であり、Appleのファイル形式ではありません。

仕様項目 この例での要件
メッセージの目的 現在の選択内容を要約する
英語のソース Selected 3 tiles in 2 groups.。両方の数値は実行時に渡される
引数1 タイル数。tile の形を制御する
引数2 グループ数。group の形を制御する
数値の表現 各引数について、Xcodeが記録した型と書式指定子を保持する
翻訳での自由度 各引数の意味を保ったまま文の順序を変えてよい
必須の挙動 それぞれの名詞が対応する数に一致する

プロジェクトで実際に使われているカタログ、テーブル、キーも記録します。翻訳時に代わりのキーを作らないでください。Appleの準備ガイドでは、ローカライズ可能なAPIによってビルド時にカタログが生成されること、および table または tableName パラメータでカタログを選ぶことが説明されています。文字列の文脈を説明するコメントにも対応しています。Preparing your app’s text for translation

役に立つ架空のコメントは次のとおりです。選択内容の要約。引数1は選択されたタイルの数です。引数2は、それらのタイルが含まれるグループの数です。2つの数はそれぞれ独立して変わります。それぞれの数を対応する名詞と結び付けてください。 数値型が同じ2つの引数を区別するのに十分な情報を翻訳者に伝えられます。

カタログで複数形の変化を個別に準備する

まず、アプリのローカライズ可能なソースにメッセージを追加して、プロジェクトをビルドします。String Catalogエディタで該当キーをControlキーを押しながらクリックし、Vary by Plural を選びます。Appleの説明によると、Xcodeは補間の書式指定子を判定し、その言語の複数形を追加して、最初は既存の値を各バリアントのフィールドに入力します。あらかじめ入力された値も編集が必要です。Localizing and varying text with a string catalog

英語のソースでは、意図する表示結果に Selected 1 tile in 1 group.、Selected 3 tiles in 1 group.、Selected 1 tile in 2 groups. が含まれます。タイル数だけに基づく選択肢を1つ設けても、すべての組み合わせを正しく表現できません。

AppleのString Catalogのデモでは、置換を使って複数の引数を変化させる方法が紹介されています。各置換には複数形のケースが含まれ、インスペクタには引数の位置とC言語形式の書式指定子が表示されます。実行時には、周囲のメッセージに選択された置換が組み合わされます。Discover String Catalogs

2つの独立した数には、この仕組みを使います。数に合わせて変化させる語は、文の周囲に固定の複数形の名詞として残さず、対応する変化の中に入れます。エディタで可能であれば置換に意味のわかる名前を付け、対応関係を確認します。タイルの置換は引数1、グループの置換は引数2を引き続き使う必要があります。

すべての対象ローカライズに英語の分岐構成をそのまま再現するよう求めないでください。Appleの説明によると、Xcodeは言語ごとの複数形の変化を追加します。ソースローカライズに変化を追加すると翻訳にも反映されますが、別のローカライズだけに追加した場合は、そのローカライズだけに適用されます。書き出す前に、対象の分岐を確認してください。Localizing and varying text with a string catalog

文言の順序を変えても引数の識別を保つ

文中でのプレースホルダーの位置と引数番号は、異なる役割を持ちます。翻訳では、アプリが値を渡す順序は変えずに、グループ数をタイル数より先に置く必要があるかもしれません。

Appleの書式指定子リファレンスでは、n$ を使った位置指定が説明されています。たとえば %1$lld は long long 整数変換を使う引数1、%2$lld は同じ変換を使う引数2を指します。%d は異なる整数表現を示し、%lld の短縮表記ではありません。このリファレンスはアーカイブされたドキュメントなので、現行のカタログのワークフローと併せて、これらの確立された書式規則を確認するために使ってください。String Format Specifiers

例示用の書式の断片 Groups: %2$lld; tiles: %1$lld を考えてみましょう。引数1が3、引数2が2なら、意図する出力は Groups: 2; tiles: 3 です。この断片が示すのは引数の順序だけです。文法に応じた複数形の選択を実装するものではないため、カタログの置換の代わりにはなりません。

プレースホルダーは意味、番号、型を照合してください。パーセント記号が2つ残っていることだけ確認しても、数の入れ替わりは見逃します。型だけを確認しても、どちらの値も整数なので入れ替わりを検出できません。逆に、翻訳に合わせてアプリの引数の順序を変えると、そのエントリを使う他のすべての翻訳の仕様も変わってしまいます。

引き渡しの際は、文言を調整しつつも、書き出された引数の対応関係と書式上の型を保持するよう翻訳者に伝えます。置換の構造を変更する場合は、仕様に照らした明示的な確認が必要です。語順の変更は適切な場合があります。

翻訳者が返却できるパッケージを書き出す

書き出す前に、プロジェクトの Use Compiler to Extract Swift Strings ビルド設定を有効にし、Swiftのローカライズ可能な文字列が含まれるようにします。Projectナビゲータでプロジェクトを選び、Product > Export Localizations を選択して、必要なローカライズと保存先を指定し、書き出します。Appleの説明には、これらの手順と、生成される .xcloc パッケージが記載されています。Exporting localizations

2種類のカタログ拡張子は、それぞれ役割が異なります。プロジェクトの .xcstrings ファイルにはString Catalogが格納されます。書き出された .xcloc パッケージは翻訳者への引き渡し用で、Localized Contents フォルダにはXLIFFが含まれ、Notes フォルダには補足テキストを含められます。表示される文だけの2列リストにするのではなく、仕様のメモを添えてパッケージを送ります。Exporting localizations

翻訳ツールがXLIFF内のString Catalogの変化に対応しているか確認します。Appleの説明によると、カタログ由来の変化識別子には文字列キーと変化の設定が記録され、書き出し時の表現には Localization Prefers String Catalogs 設定が使われます。往復の間、これらの構造を保つ必要があります。Discover String Catalogs

実務で使える納品物のチェックリストは次のとおりです。これは、記載されたパッケージ構造とこの例の仕様から導いたワークフロー上の推奨事項です。

  • 関連リソースを含めた翻訳済みの .xcloc パッケージを返す。
  • 意図的な構造変更を記録した場合を除き、メッセージ識別子と変化のパスを保持する。
  • 対象ローカライズで必要な複数形の分岐に、対象言語のテキストを用意する。
  • 引数の識別、数値型、置換の対応関係を保持する。
  • 書き出し後に受け取ったソースの変更があれば伝え、読み込み前に調整できるようにする。

翻訳者のツールが変化のあるエントリを保持できない場合は、Xcodeで書き出したローカライズを編集するか、プロジェクトのカタログに翻訳を入力します。Appleの説明によると、XcodeではXLIFFのターゲットやString Catalogを編集でき、以後の書き出しにもカタログの変更が含まれます。テキストだけをフラットにやり取りすると、変化の構造を誰かが再構築しなければなりません。Editing XLIFF and string catalog files

返却されたパッケージを読み込み、実際の変更を確認する

比較できるよう、元の書き出しデータも手元に残します。翻訳済みパッケージが戻ったら、プロジェクトを選択し、Product > Import Localizations を選びます。Xcode Localization Catalogのフォルダを指定します。読み込み画面で Issues View を確認して警告とエラーを調べ、読み込みを完了する前に File View で変更を確認します。Appleの説明によると、比較エディタでは左側に読み込むバージョン、右側にプロジェクトの現在のバージョンが表示されます。Importing localizations

String Catalog由来の文字列について、Appleの説明によると、翻訳を該当するString Catalogに戻して読み込めます。読み込み後、選択内容の要約エントリを開き、2つの置換、それぞれの引数との対応関係、対象の分岐を確認します。Discover String Catalogs

問題があるように見える場合は、次の順序で確認します。エントリが見つからない場合は、テーブルとキーを元の書き出しデータと照合します。複数形のバリアントが見当たらない場合は、返却された変化の構造を比べます。数と名詞の組み合わせが違う場合は、引数の対応関係を確認します。特定の組み合わせだけが不自然な場合は、アプリのコードを変更する前に、その分岐のテキストを確認します。この手順は例の依存関係に沿ったものであり、Xcodeが仕様違反をすべて自動検出するという意味ではありません。

数が異なるケースをテストして引数の入れ替わりを見つける

読み込みに成功すれば、Xcodeが納品物を受け付けたことは確認できます。この例では、挙動のテストも必要です。アプリのテストデータまたは開発用フィクスチャを使って、次の組み合わせを表示します。期待される文は英語ソースの仕様を示すものです。対象言語の文言と分岐の選択は、対象ローカライズに従う必要があります。

タイル数 グループ数 英語ソースで期待される出力 確認できること
1 1 Selected 1 tile in 1 group. どちらも単数形になること
3 1 Selected 3 tiles in 1 group. タイル数に応じた個別の変化
1 2 Selected 1 tile in 2 groups. グループ数に応じた個別の変化
3 2 Selected 3 tiles in 2 groups. 引数の入れ替わりを見つけやすい異なる値

アプリが選択なしの状態を表示できる場合は、数が0のケースも追加します。また、各対象ローカライズで必要なすべての複数形カテゴリーを確認できる値を選びます。上の4行で網羅できるのは英語の単数形と複数形の組み合わせであり、対象言語のすべての分岐ではありません。

Macアプリを対象ローカライズで実行するには、Product > Scheme > Edit Scheme を選び、Run を選択して Options を開きます。App Language を設定し、必要に応じて App Region も指定してから、エディタを閉じ、Macの実行先を選んで実行します。Appleのドキュメントでは、このスキームを使ったテスト手順が説明されています。Testing localizations when running your app

表示されたメッセージを読み、デスクトップのインターフェイス内で収まるか確認します。数が正しい名詞と結び付いており、必要な各分岐が正しく動作し、返却された構造が意図した仕様と一致していれば、このラベルに必要な挙動を保ったまま翻訳を往復できたことになります。次回の文言変更も同じ明確な要件に照らして確認できるよう、納品物に仕様のメモを添えておきます。

参考資料