iOSアプリをローカライズする
共有ファイル内のロケールを保持したまま、アップルのストリングカタログや従来形式のリソースを翻訳し、Xcodeとアプリで検証します。
iOSアプリでは、リソースファイルに言語を追加しても、ローカライズ済みの文字列を取得する既存の呼び出しをそのまま使えます。Lingo.devが翻訳するのは、そのリソースです。ユーザーに表示するバンドル、テーブル、ロケール、バリエーションは、引き続きXcodeとアプリが決定します。
プロジェクトが現在読み込んでいる形式を使ってください。ストリングカタログは1つの.xcstringsファイルに複数の言語を格納しますが、.stringsと.stringsdictのリソースはロケールごとにファイルを分けます。この違いによって、翻訳結果の書き込み先と、更新時に保護すべき内容が決まります。
正とするリソースを決める #
ストリングカタログを使うプロジェクトでは、開発言語、対応する翻訳先言語、アプリが読み込むカタログを確認します。Xcode 15で導入された.xcstringsは、通常Localizable.xcstringsという名前で使われます。機能やバンドルごとにメッセージを複数のカタログに分けている場合は、ローカライズする画面で使うカタログをすべて含めてください。
従来形式のリソースでは、関連する.lprojディレクトリ、文字列テーブル、複数形辞書を確認します。Base.lprojにはベースとなるインターフェースのリソースが含まれる場合があります。ただし、それがあるだけで、翻訳に使うソース言語や文字列テーブルを判断できるとは限りません。プロジェクトの開発言語設定とファイル構成の整合性を保ってください。
翻訳を始める前に、画面のテキストをローカライズ済み文字列の取得処理に結び付けてください。ファイルを翻訳するだけでは、コードに直接記述された画面上の文字列は置き換わらず、Xcodeのターゲットにリソースが登録されることもありません。レビュー担当者のために、話者や画面を説明するコメントは残してください。既存のストリングカタログ用ハンドラーはコメントを保持しますが、翻訳単位のヒントには含めません。生成に必要な文脈は、ローカライゼーションエンジンが対応するガイダンスに記載してください。
共有ストリングカタログを設定する #
プロジェクトのルートから、現行版のCLIをインストールしてリンクします。
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,fr --files 'App/Localizable.xcstrings' --yes
lingo linkそのパスにカタログがある場合、生成される.lingo/config.jsonは次の構造になります。
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es", "fr"],
"files": [{ "pattern": "App/Localizable.xcstrings" }]
}プレースホルダーをコピーするのではなく、リンク時に生成された識別子をそのまま使ってください。拡張子に応じてxcode-xcstringsが選択されます。各翻訳先の出力は同じカタログパスに書き込まれ、ソースと他のロケールを保持したまま、新たなロケールのエントリが追加されます。この共有ファイル形式では、個別のtargetPathは使用できません。
ソースの値は、共有構造の中に格納されます。
{
"sourceLanguage": "en",
"strings": {
"Welcome": {
"comment": "Greeting on the signed-in home screen",
"localizations": {
"en": { "stringUnit": { "state": "translated", "value": "Welcome" } }
}
}
},
"version": "1.0"
}翻訳後は、enと並んで、指定したロケールのエントリが追加されていることを確認してください。ハンドラーはソースの複数形やデバイス別バリエーションの末端要素にも対応し、shouldTranslate: falseが指定されたエントリはスキップします。ソース言語のローカライズがないエントリでは、キーがソーステキストとして使われます。技術的な識別用のキーは、本来伝えたいメッセージの代わりにはなりません。アップルのストリングカタログでは、これらの選択ルールと、現在のソースと既存のカタログの整合性を保つ必要がある理由を説明しています。
従来形式のファイルは別のパスで管理する #
従来形式のプロジェクトでは、共有カタログのエントリの代わりに、次のファイルエントリを使います。
[{ "pattern": "App/en.lproj/Localizable.strings" }, { "pattern": "App/en.lproj/Localizable.stringsdict" }]プロジェクトに実際に存在するリソースだけを含めてください。拡張子に応じてハンドラーが選択されます。スペイン語の出力先はApp/es.lproj/です。プロジェクトの開発言語設定は、ここで選んだソースと一致させてください。
文字列のキーと書式プレースホルダーは、実行時に守るべき仕様の一部です。%@、位置指定引数、呼び出し元が想定する型を保持してください。.stringsdictには複数形変数の構造が含まれるため、書式文字列との整合性を保つ必要があります。どちらも任意のXMLやテキストとして扱わず、アップルの文字列と文字列辞書で、それぞれ固有の仕様を確認してください。
翻訳してマージ結果を確認する #
置き換える前に、現在のカタログをバージョン管理に保存するか、別途コピーを作成してください。ローカルでの編集を保護するには、--waitを付けずに送信し、取得前にlingo pull --dry-runを確認します。差異があれば、強制的に上書きせず、内容を突き合わせて整合させてください。完了を待って書き戻す方式では、取得処理とは異なり、書き戻し直前の競合チェックは行われません。レビュー済みの翻訳を保持するを参照してください。
初回の翻訳を問題なく進めるため、次のコマンドは、待機中にカタログが変更されない場合に限って使ってください。既存のプロジェクトにロケールを追加する場合は、まず既存のロケールに対する通常のソース更新を完了し、結果を取得して確認します。その後、ソースのリビジョンを固定したまま、ロケールの追加と未翻訳分の補完を行ってください。必要な順序は言語を追加するで説明しています。
lingo push --backfill-missing --wait共有カタログでは、ファイルがすでに存在していても、ロケールごとに処理計画が作成されます。新しいファイル名を探すのではなく、指定したロケールのエントリを確認してください。初回の通常の送信では、翻訳せずにソースの基準状態だけを確立することもできます。通常のソース変更後はlingo push --waitを使います。完了を待たない場合は、送信を行ったチェックアウトでlingo pullを使い、記録された結果を取得してください。
文言を修正する場合は、Xcodeで翻訳先のエントリを編集してください。CLIの--forceでは、変更されていないカタログ内の翻訳が引き続き再利用されることがあります。ガイダンスの変更後に1つのエントリを再生成するには、ソースと周囲の翻訳を保持するカタログの修正手順に従ってください。
lingo purgeは、ソースと翻訳先が同じパスを共有するため、ストリングカタログをスキップします。選択した翻訳を再生成するには、ストリングカタログの修正ワークフローを使ってください。
Xcodeと代表的な画面で検証する #
出力をXcodeで開き、カタログまたは従来形式のファイルが、意図したターゲットとバンドルに含まれていることを確認します。プロジェクトの既存のスキームでビルドしてください。翻訳先言語の構成で実行し、単純なラベル、書式付きの値、複数形またはデバイス別バリエーションを含む画面を確認します。
翻訳先言語のプレースホルダーを、呼び出し元のコードと照合してください。各言語で異なる複数形が選ばれるよう、数値を変えて動作を確認します。英語のカテゴリーだけでは、すべての翻訳先言語の仕様を網羅できません。変更していないロケールがマージ後のカタログに残っていることも確認してください。長いラベル、アクセシビリティ用テキスト、表示の切り詰めに加え、該当する場合は右から左への表示動作もレビューします。
Xcodeのビルドチェックではリソースの問題を検出できますが、意味の確認は言語のレビュー担当者や適切な測定で行います。lingo checkだけでは、.xcstringsの完全性や、アップルの複数形処理が正しく機能することは確認できません。
自動化でも共有ファイルを保持する #
ソース、承認済みの翻訳、設定、.lingo/lock.jsonをまとめて管理し、定期的な作業にはGitHub AppまたはCIランナーを選びます。ランナーは認証と状態を自ら管理し、レビュー可能な形で書き戻します。ストリングカタログの差分は、共有ファイルへの変更としてレビューしてください。受け入れる前に、ソースのリビジョン、変更されたロケール、保持されたロケールを確認します。
クロスプラットフォームのプロジェクトでは、XML修飾子とARB生成に、それぞれ専用のアンドロイドとFlutterのワークフローを使ってください。各プラットフォームで、リソースの読み込みと実際に描画された画面を個別に確認する必要があります。