Lingo.devのCLIは、設定済みのローカライゼーションエンジンを通じて、Xcodeの.xcstringsString Catalogs（）を翻訳します。String Catalogsは、Xcode 15で導入されたAppleの最新ローカライズ形式で、すべての言語を1つのJSONファイルにまとめて管理できます。CLIはこのファイルを直接更新するため、ロケールごとのディレクトリは必要ありません。
このガイドでは、iOS アプリをエンドツーエンドでローカライズする流れを紹介します。CLI の設定、ローカルでの翻訳、さらに GitHub App を使った自動化まで行うことで、プッシュのたびに翻訳を反映してリリースできるようになります。
デモリポジトリ
一緒に進めるには、lingodotdev/ios-app-localization-example を clone または fork してください。このリポジトリには、String Catalog と Lingo.dev CLI の設定を含む、すぐに試せる Xcode プロジェクトが用意されています。
String Catalogsの仕組み#
Xcode 15以前のiOSローカライズでは、.stringsディレクトリごとに分かれた.stringsdictや[locale].lproj/ファイルを個別に管理する必要がありました。String Catalogsでは、これがXcodeによって自動管理される1つのLocalizable.xcstringsファイルに置き換わります。
SwiftUIまたはUIKitで文字列をローカライズ対象として指定すると、Xcodeがビルド時にそれを検出し、String Catalogにエントリを追加します。各エントリには、ソース文字列、設定された各ロケール向けの翻訳、そして翻訳者に文脈を伝える任意のコメント欄が含まれます。
| 項目 | 従来の.strings | String Catalogs .xcstrings |
|---|---|---|
| ファイル数 | テーブルごと・ロケールごとに1つ | 1ファイルですべてのロケール |
| 形式 | キーと値のテキスト形式 | 構造化JSON |
| 複数形対応 | 別途.stringsdictファイルが必要 | 複数形ルールを標準サポート |
| Xcode連携 | 手動でエクスポート／インポート | 自動検出 |
| 翻訳者向けメモ | 非対応 | エントリごとのコメント欄 |
CLI はファイル拡張子から .xcstrings 形式を自動検出し、この JSON 構造を解析して各エントリをローカライゼーションエンジン経由で翻訳し、コメント、複数形ルール、メタデータを保持したまま同じファイルに書き戻します。
前提条件#
ローカライゼーションエンジンを作成する
すべての翻訳はローカライゼーションエンジンを通じて処理されます。これは、使用するLLMモデルや、適用するglossary、ブランドボイス、rulesを決める設定です。Lingo.dev dashboardで作成し、API keyを生成してください。
Node.jsを確認する
CLI の利用には Node.js 22 以上が必要です。
node -vXcodeでローカライズを有効にする
Xcodeプロジェクトで Project Settings > Info > Localizations に移動し、対象言語を追加してください。追加した各ロケールに対して、XcodeがString Catalogのエントリを作成します。詳しくはAppleのlocalization documentationを参照してください。
CLI をインストールして設定する#
CLI をインストールして認証したら、プロジェクトをセットアップします。手順全体は Quickstart を参照してください。
npm install -g @lingo.dev/cli
lingo loginプロジェクトルートで lingo init を実行し、表示されるプロンプトに回答します（ソースロケール、ターゲットロケール、String Catalog を指定するファイルパターン）。続けて lingo link を実行すると、プロジェクトが組織とエンジンに紐づけられます。これにより .lingo/config.json が書き込まれます。
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es", "fr", "de", "ja"],
"files": [{ "pattern": "MyApp/Localizable.xcstrings" }]
}.lingo/config.json は必ずコミットしてください。何を翻訳対象にするかを定義する source of truth です。.xcstrings 形式はファイル拡張子から検出されます。String Catalog はすべてのロケールを 1 つのファイルに保持するため、パターンにロケール用プレースホルダーは不要です。CLI はソース言語のエントリを読み取り、すべてのターゲット言語を同じファイルへ書き戻します。完全なスキーマは configuration reference を参照してください。
複数のString Catalogを使う場合
複数の String Catalog ファイルを使っている場合（たとえばフレームワークターゲットごとに 1 つずつある場合）は、それぞれに files エントリを追加してください。
{
"files": [
{ "pattern": "MyApp/Localizable.xcstrings" },
{ "pattern": "MyAppWidgets/Localizable.xcstrings" }
]
}ローカルで翻訳する#
プロジェクトルートから、最初の翻訳を実行します。
lingo push --backfill-missingCLI は String Catalog を読み込み、不足しているエントリをローカライゼーションエンジン経由ですべて翻訳し、実行完了を待ってから結果を .xcstrings ファイルに書き戻します。Xcode でそのファイルを開けば、設定した各ロケールの翻訳が反映されているのを確認できます。
ソース文字列を編集したあとは、通常の lingo push で差分だけが翻訳されます。ソースが変わっていないエントリは、lockfile で追跡され、サーバー側でスキップされます。
lingo push翻訳者向けメモ#
String Catalogsでは、各エントリにコメント欄を持たせることができ、CLIはそのコメントを翻訳リクエストに含めます。これらのコメントはローカライゼーションエンジンに文脈を伝え、用語の曖昧さを解消したり、トーンを指定したり、文字列がUIのどこに表示されるかを説明したりするのに役立ちます。
Xcodeでは、String Catalogエディタで文字列を選択し、インスペクタパネルでコメントを追加できます。コメントは.xcstringsJSONに保存されます。
{
"sourceLanguage": "en",
"strings": {
"Set": {
"comment": "Refers to a collection of items, not the verb",
"localizations": { }
}
}
}CLIはこのコメントを文字列と一緒に送信することで、モデルを正しい解釈へ導きます。たとえば文脈のない"Set"は、多くの言語で動詞として訳される可能性がありますが、コメントがあればその曖昧さを解消できます。さらに多くのパターンについては、Translator Notesを参照してください。
複数形#
String Catalogsは、CLDR plural rulesを使って複数形をネイティブに処理します。Xcodeで複数形バリエーションを定義すると、String Catalogには対象言語で必要な各複数形カテゴリ（zero、one、two、few、many、other）のルールが保存されます。
CLIは翻訳時にもこの構造を維持し、各対象ロケールに対して正しい複数形カテゴリを生成します。英語で使うカテゴリは2つ（oneとother）ですが、アラビア語では6つ、ポーランド語では4つ、日本語では1つ必要です。こうした違いは、ローカライゼーションエンジンが自動的に処理します。
GitHub App で自動化#
継続的ローカライゼーションのために、リポジトリへ Lingo.dev GitHub App をインストールしてください。CI ランナーも、API key のシークレットも、管理用の lockfile も不要です。インストールして .lingo/config.json（その engineId を含む）を指定すれば、プッシュやプルリクエストに自動で反応し、変更されたソース文字列を検出してエンジン経由で翻訳し、更新済みの .xcstrings をブランチにコミットするか、プルリクエストを作成します。
自分で実行したい場合は？
lingo push は、自前の CI ジョブ（Node.js が動作する任意のランナー）から実行して、結果をコミットすることもできます。認証には LINGO_API_KEY を使用します。ランナーベースのパターンについては CI/CD ワークフロー を参照してください。
デプロイ前に確認する#
未翻訳の文字列を本番環境へ出さないためのデプロイゲートとして lingo check を使えます。不足している翻訳や古くなった翻訳を検出し、未対応の項目が残っている場合は非ゼロステータスで終了します。
lingo checkこれをビルド前の独立した CI ステップとして追加してください。
