Macアプリのすべてのローカライズキーを監査するには、関連するターゲットをビルドし、各文字列テーブルをサポート対象のすべての言語と照合したうえで、実行中のアプリでメッセージのバリエーションをテストします。カタログの完成度と実行時の正しい表示は、別々に確認する必要があります。

このワークフローは、XcodeでMacデスクトップアプリを保守する開発者向けです。具体的には、メッセージの欠落、翻訳の未完了、引数の誤り、表示上の問題を追跡可能な記録として作成します。例では架空のラベルと件数を使っており、実際のプロジェクトに適用できる監査方法を示しています。

完了したメッセージの定義

まず、小さな監査ワークシートを用意します。アプリのターゲット、リソースバンドル、文字列テーブル、キー、サポート対象のローカライズ、必要なバリエーション、翻訳状態、実行時の結果を記録します。同じキー文字列が別のリソースにあっても欠落を見落とさないよう、バンドル・テーブル・キーの組み合わせごとに別々のメッセージとして扱います。

Appleのドキュメントによると、ローカライズ可能なAPIではテーブルとバンドルを指定でき、メインバンドル以外のリソースを検索するには適切なバンドルが必要です。そのため、既定の Localizable.xcstrings ファイルだけを確認しても、アプリ内のほかの場所にあるメッセージを見落とす可能性があります。アプリのテキストを翻訳用に準備するを参照してください。

プロジェクトエディタで、プロジェクトのサポート対象ローカライズを確認します。Project の下にあるプロジェクトを選択し、Info を開いて Localizations を確認してください。どのリソースが各ローカライズに含まれるかも確認します。Appleの言語と地域のサポートを追加するでは、これらのプロジェクト設定とリソース選択について説明しています。

ワークシートでは、Localization A、Localization B、Localization Cのような架空の別名を使えます。作業記録には、各別名とプロジェクトの実際のローカライズ識別子との対応を残します。これらはワークシート上のラベルであり、Xcodeに入力する値ではありません。

監査では、次の完了基準を使います。これは提案するレビュー方法であり、Appleが定義する完了ステータスではありません。

確認項目 記録する証拠
棚卸し メッセージのターゲット、バンドル、テーブル、キーが特定されている。
検出 メッセージがコードから抽出されているか、意図的に手動管理されている。
網羅性 必要なすべてのローカライズに、必要なメッセージのバリエーションがある。
引数 各引数が意図した意味と互換性のある型を保っている。
実行時 関連するMacインターフェイスに正しいメッセージと値が表示される。
対応状況 各指摘が修正済み、理由を明記して意図的に除外済み、または未対応のいずれかである。

翻訳をレビューする前にカタログの一覧を作る

プロジェクトに既存の文字列カタログがあれば開きます。ターゲットにカタログがない場合、Appleが案内する作成手順は File > New > File from Template を選び、次に String Catalog を選択する方法です。既定の名前は Localizable です。コードが想定するテーブル名を使ってください。Product > Build を選ぶと、カタログに内容が追加され、更新されます。文字列カタログでテキストをローカライズし、変化させるを参照してください。

ビルドが1回成功しただけで一覧が完成したと考えず、関連するMacのスキームをそれぞれビルドします。Appleによると、文字列の抽出では現在のスキームとプラットフォームの文字列が検出されます。あるビルドに存在しないメッセージは、未使用と判断する前に調査してください。この範囲については文字列カタログを検出するで説明されています。

Use Compiler to Extract Swift Strings のビルド設定を確認します。Appleは、ローカライズ可能なSwiftのテキストをすべてローカライズ用書き出しに含めるため、この設定を有効にするよう明記しています。翻訳作業用の交換データが必要な場合は、プロジェクトを選択して Product > Export Localizations を選び、必要なローカライズを指定します。書き出される .xcloc パッケージはXcode Localization Catalogであり、個々の .xcstrings 文字列テーブルとは異なります。ローカライズの書き出しを参照してください。

次に、アプリの通常のデスクトップ画面を順に確認します。メインウィンドウ、メニュー、ツールバー、設定、パネル、空の状態、件数によって変わるラベルなどです。見つけたアプリ固有のメッセージごとに、ワークシートの項目を探します。表示されたインターフェイスから一覧へ逆向きに確認することで、カタログに一度も追加されなかったテキストを見つけやすくなります。

抽出ですべての任意の文字列式が検出されるとは限りません。Appleはローカライズ可能なAPIを通じた抽出について説明しています。想定したメッセージが見つからない場合、手動で重複項目を追加する前に、コードでそのメッセージをどう作成し渡しているかを確認します。アプリのテキストを翻訳用に準備するを参照してください。

抽出、検索、実行時のフォーマットを分けて考える

これらの操作で確認できる内容はそれぞれ異なります。抽出では、開発時にXcodeがメッセージを検出できるかを確認します。検索では、実行中のアプリがどのローカライズ済みリソースを要求するかを確認します。実行時のフォーマットでは、選択されたメッセージに表示する可変の内容を渡します。

SwiftUIでは引数の型が重要です。Text("Open collection") のようなリテラルは、ローカライズされた検索に使われます。対応するイニシャライザに通常の String 変数を渡すと、通常はローカライズされず、その変数が表示されます。Appleはこの違いをLocalizedStringKeyで説明しています。

変数から LocalizedStringKey を明示的に作成すると検索が要求されますが、それだけでは、ビルド時の抽出で変数が取り得るすべての値が検出されたとは言えません。動的に選択されるキーについては、許可されているキーの集合全体をカタログと照合します。テスト中にたまたま使われた値だけを頼りにせず、一致しない値をすべて調査してください。

文字列補間には、メッセージの構成という役割もあります。SwiftUIでは、フォーマット指定子を含むローカライズ済みメッセージを検索し、描画前に補間値を代入できます。AppleはTextのドキュメントで、ローカライズ可能なテキストの作成に補間を使うことを推奨しています。

項目数を示す例示用メッセージを考えてみましょう。カタログにはローカライズ可能なメッセージ構造とバリエーションを保存し、変化する件数は実行時の動作に任せます。件数が変わるだけで、1と24のために別々のキーを管理する必要はありません。

見た目が自然なラベルだけでは、検索に成功した証拠として不十分です。Appleによると、ローカライズ済みの値が見つからない場合、SwiftUIはキーそのものを表示することがあります。キーが読みやすいソーステキストなら、検索の問題が通常のラベルのように見える場合もあります。表示結果と合わせて、選択されたローカライズとカタログ項目を確認してください。ビューをローカライズ用に準備するを参照してください。

すべての言語と必要なバリエーションを確認する

一度に1つのテーブル、1つのローカライズを確認します。メッセージごとに翻訳状態、テキスト、引数、展開されたバリエーションを確認します。周囲のメッセージが完成していても、未完了の行は未対応のままにします。

Appleのカタログワークフローでは、New、Needs Review、翻訳済みの項目、Stale 文字列を区別します。stale項目はコードから見つからなくなった文字列です。手動管理の項目は、同期時に自動で更新または削除されません。翻訳を削除する前に、staleキーが不要であることを確認してください。文字列カタログを検出するを参照してください。

件数に応じて変化するメッセージの場合、補間されたキーをControlキーを押しながらクリックし、Vary by Plural を選びます。Xcodeが各ローカライズに用意するすべての形式を確認してください。必要な形式はローカライズごとに異なることがあるため、ソースローカライズと行数が同じかどうかだけでは十分に確認できません。カタログにデバイス別バリエーションがある場合は、Mac固有の値と一般値の両方を確認します。Appleは文字列カタログでテキストをローカライズし、変化させるでこれらの操作を説明しています。

引数は見た目だけでなく意味も確認します。項目数を複数のグループにわたって示す架空のメッセージなら、どの引数が項目数を表し、どの引数がグループ数を表すかを特定します。翻訳で配置が変わることはあっても、それぞれの意味は保つ必要があります。Appleのカタログの解説では、引数の位置、型指定子、複数形の置換について文字列カタログを検出するで説明しています。

短いラベルの意味が曖昧なら、コンテキストを追加します。Open へのコメントで、それがコレクションの行に対する操作だと示せます。SwiftUIの comment パラメータは、このコンテキストをローカライズ用出力に渡します。Appleはビューをローカライズ用に準備するで説明しています。

未完了の作業が分かる網羅性マトリクスを使う

単一のパーセンテージはカタログの進捗を追うのに役立ちますが、監査では網羅性と動作を別々の列で確認する必要があります。次の例は、その理由を示しています。数値は架空のものであり、アプリの実測値ではなく、メッセージとローカライズの組み合わせ数を表します。

必須メッセージが48件あり、サポート対象のローカライズが3つあるとします。必要な組み合わせは48に3を掛けた144件です。各組み合わせに複数形やデバイス別の分岐がさらに含まれる場合、それぞれも確認する必要があります。

ローカライズ 必要な組み合わせ カタログ確認済み 実行時確認済み
Localization A 48 48 48
Localization B 48 46 44
Localization C 48 48 45
合計 144 142 137

この例では、2件の組み合わせでカタログ作業が残り、7件で実行時確認が完了していません。これらのグループは重複する可能性があるため、単純に足しても未完了メッセージの個数は正確に分かりません。各指摘を該当する行に記録してください。

未完了の行ごとに、次の具体的な作業を記録します。ソースメッセージの欠落を探す、複数形の分岐を完成させる、引数を確認する、バンドル選択を調べる、またはより狭い幅でインターフェイスを再確認する、などです。これにより、マトリクスを見た目だけの進捗報告ではなく、修正作業の一覧として使えます。

サポート対象のすべてのローカライズでMacアプリを実行する

繰り返しアプリを確認するには、Xcodeのスキーム設定を使います。Product > Scheme > Edit Scheme を選び、Run を選択して Options を開き、App Language と App Region を指定します。ダイアログを閉じ、Macの実行先を選んでアプリを起動します。監査で対象とする組み合わせごとに繰り返してください。Appleはアプリ実行時のローカライズテストでこの手順を説明しています。

実行のたびに同じ経路でインターフェイスを操作します。空のコレクション、項目が1つの場合、複数項目、長めの架空のラベルなど、関連する状態ごとにメッセージを確認してください。複数形のメッセージでは、そのローカライズに存在する分岐を確認するために必要な追加の値を選びます。少数の固定件数を試すだけでは、すべての分岐を網羅したことにはなりません。

文章全体、代入された値、折り返し、省略表示、メニューやコントロールの幅を確認します。メッセージに2つの件数がある場合は、それぞれを独立して変化させます。たとえばグループ数を固定したまま項目数を変えると、引数の割り当てミスを見つけやすくなります。

SwiftUIプレビューを使うと修正をすばやく繰り返せます。Appleはプレビューの locale 環境値の設定と、ローカライズを追加または読み込んだ後に複数のローカライズ済みプレビューを作成する方法をサポートしています。問題のあるビューの再確認に使った後、実際のアプリの経路でも検証してください。ローカライズのプレビューを参照してください。

必須のメッセージとローカライズの各組み合わせについて対応状況を記録し、必要な分岐を確認したら監査を完了します。一覧、テスト経路、未解決の指摘をまとめて保存してください。この記録があれば次の監査にすぐ取りかかれます。変更されたメッセージの場所、想定される引数、必要なバリエーション、表示を確認する再現可能な方法が分かるためです。

参照元