Communitygithub.com

ローカライゼーションと国際化 (i18n)

String Catalogを使用したアプリのローカライズ、型安全なシンボル生成(Xcode 26+)、複数形処理、RTLレイアウト、ロケール対応フォーマット、および .strings ファイルからの移行を行うための包括的な i18n パターン(Xcode 15-26対応)。

ローカライゼーションと国際化 (i18n) とは?

このスキルは、Appleプラットフォーム向けアプリのローカライゼーションと国際化(i18n)に関する包括的なガイドです。Xcode 15で導入されたString Catalog(.xcstrings)を中心に、従来の .strings や .stringsdict ファイルに代わる統一フォーマットを用いた翻訳管理、SwiftUI/UIKitでのローカライゼーションAPI、複数形処理、RTL(右から左)言語のサポート、ロケールに応じた日付・数値・通貨のフォーマット方法をカバーします。さらに、Xcode 26以降で利用可能な自動シンボル生成、#bundle マクロ、AIコメント生成といった高度な機能についても説明します。このガイドは、アプリを複数言語に対応させる必要がある開発者、既存のローカライゼーションファイルから移行する開発者、またはユーザーインターフェースを国際化するためのベストプラクティスを学びたい開発者にとって役立ちます。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/IGTA-Tech/claude-skills-research/tree/HEAD/Axiom/.claude-plugin/plugins/axiom/skills/localization

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

ローカライゼーションと国際化

String Catalogを使用したアプリローカライゼーションの包括的ガイド。Apple Design Award Inclusivityの受賞アプリは、常に複数言語と優れたRTL(右から左)サポートを備えています。

概要

String Catalog(.xcstrings)は、Xcode 15で導入されたアプローカライゼーション管理のための統一フォーマットです。従来の .strings や .stringsdict ファイルを、JSONベースの単一フォーマットに置き換え、保守、差分表示、翻訳ワークフローとの統合が容易になります。

このスキルでは、String Catalog、SwiftUI/UIKitのローカライゼーションAPI、複数形処理、RTLサポート、ロケール対応フォーマット、およびレガシーフォーマットからの移行戦略をカバーします。

このスキルを使用すべき場合

  • Xcode 15+ でString Catalogをセットアップする場合
  • SwiftUIおよびUIKitアプリをローカライズする場合
  • 複数形を正しく処理する場合(多くの言語で重要)
  • RTL言語(アラビア語、ヘブライ語)をサポートする場合
  • ロケールに応じて日付、数値、通貨をフォーマットする場合
  • レガシーな .strings / .stringsdict ファイルから移行する場合
  • App Shortcuts および App Intents をローカライズ用に準備する場合
  • 欠落した翻訳や誤った複数形をデバッグする場合

システム要件

  • Xcode 15+: String Catalog(.xcstrings)用
  • Xcode 26+: 自動シンボル生成、#bundle マクロ、AIコメント生成用
  • iOS 15+: LocalizedStringResource 用
  • iOS 16+: App Shortcuts のローカライズ用
  • それ以前のiOSバージョンでは、レガシーな .strings ファイルを使用します

パート1: String Catalog(WWDC 2023/10155)

String Catalogの作成

方法1: Xcodeナビゲーター

  1. File → New → File
  2. "String Catalog" を選択
  3. 名前を付ける(例: Localizable.xcstrings)
  4. ターゲットに追加

方法2: 自動抽出

Xcode 15は、以下から文字列を自動抽出できます:

  • SwiftUIビュー(Text、Label、Button の文字列リテラル)
  • Swiftコード(String(localized:))
  • Objective-C(NSLocalizedString)
  • C(CFCopyLocalizedString)
  • Interface Builderファイル(.storyboard、.xib)
  • Info.plist の値
  • App Shortcuts のフレーズ

必要なビルド設定:

  • "Use Compiler to Extract Swift Strings" → Yes
  • "Localization Prefers String Catalogs" → Yes

String Catalogの構造

各エントリには以下が含まれます:

  • Key: 一意識別子(デフォルトは英字文字列)
  • Default Value: 翻訳がない場合のフォールバック
  • Comment: 翻訳者向けのコンテキスト
  • String Table: 組織化のためのコンテナ(デフォルトは "Localizable")

.xcstrings JSONの例:

{
  "sourceLanguage" : "en",
  "strings" : {
    "Thanks for shopping with us!" : {
      "comment" : "Label above checkout button",
      "localizations" : {
        "en" : {
          "stringUnit" : {
            "state" : "translated",
            "value" : "Thanks for shopping with us!"
          }
        },
        "es" : {
          "stringUnit" : {
            "state" : "translated",
            "value" : "¡Gracias por comprar con nosotros!"
          }
        }
      }
    }
  },
  "version" : "1.0"
}

翻訳の状態

Xcodeは各翻訳の状態を追跡します:

  • New(⚪) - 文字列がまだ翻訳されていません
  • Needs Review(🟡) - ソースが変更され、翻訳が古い可能性があります
  • Reviewed(✅) - 翻訳が承認され、最新です
  • Stale(🔴) - 文字列がソースコードに見つからなくなりました

ワークフロー:

  1. 開発者が文字列を追加 → New
  2. 翻訳者が翻訳を追加 → Reviewed
  3. 開発者がソースを変更 → Needs Review
  4. 翻訳者が更新 → Reviewed
  5. 開発者がコードを削除 → Stale

パート2: SwiftUI ローカライゼーション

LocalizedStringKey(自動)

String パラメータを持つSwiftUIビューは、自動的にローカライゼーションをサポートします:

// ✅ 自動ローカライズ可能
Text("Welcome to WWDC!")
Label("Thanks for shopping with us!", systemImage: "bag")
Button("Checkout") { }

// Xcode はこれらの文字列を String Catalog に抽出します

仕組み: SwiftUI は内部で LocalizedStringKey を使用し、String Catalog 内の文字列を検索します。

コメント付きの String(localized:)

Swiftコードでの明示的なローカライゼーション:

// 基本
let title = String(localized: "Welcome to WWDC!")

// 翻訳者向けコメント付き
let title = String(localized: "Welcome to WWDC!",
                   comment: "Notification banner title")

// カスタムテーブル付き
let title = String(localized: "Welcome to WWDC!",
                   table: "WWDCNotifications",
                   comment: "Notification banner title")

// デフォルト値付き(キー ≠ 英字テキスト)
let title = String(localized: "WWDC_NOTIFICATION_TITLE",
                   defaultValue: "Welcome to WWDC!",
                   comment: "Notification banner title")

ベストプラクティス: 翻訳者にコンテキストを与えるために、常に comment を含めてください。

LocalizedStringResource(遅延ローカライゼーション)

ローカライズ可能な文字列を他の関数に渡す場合:

import Foundation

struct CardView: View {
    let title: LocalizedStringResource
    let subtitle: LocalizedStringResource

    var body: some View {
        ZStack {
            RoundedRectangle(cornerRadius: 10.0)
            VStack {
                Text(title)      // レンダリング時に解決
                Text(subtitle)
            }
            .padding()
        }
    }
}

// 使用法
CardView(
    title: "Recent Purchases",
    subtitle: "Items you've ordered in the past week."
)

主な違い: LocalizedStringResource は使用されるまでルックアップを延期し、カスタムビューを完全にローカライズ可能にします。

Markdownを使用したAttributedString

// Markdown 形式はローカライゼーション間で保持されます
let subtitle = AttributedString(localized: "**Bold** and _italic_ text")

パート3: UIKit & Foundation

NSLocalizedString マクロ

// 基本
let title = NSLocalizedString("Recent Purchases", comment: "Button Title")

// テーブル付き
let title = NSLocalizedString("Recent Purchases",
                             tableName: "Shopping",
                             comment: "Button Title")

// バンドル付き
let title = NSLocalizedString("Recent Purchases",
                             tableName: nil,
                             bundle: .main,
                             value: "",
                             comment: "Button Title")

Bundle.localizedString

let customBundle = Bundle(for: MyFramework.self)
let text = customBundle.localizedString(forKey: "Welcome",
                                        value: nil,
                                        table: "MyFramework")

カスタムマクロ

// Objective-C
#define MyLocalizedString(key, comment) \
    [myBundle localizedStringForKey:key value:nil table:nil]

Info.plist のローカライゼーション

アプリ名、権限などをローカライズ:

  1. Info.plist を選択
  2. Editor → Add Localization
  3. 各言語用に InfoPlist.strings を作成:
// InfoPlist.strings (Spanish)
"CFBundleName" = "Mi Aplicación";
"NSCameraUsageDescription" = "La app necesita acceso a la cámara para tomar fotos.";

パート4: 複数形

言語によって異なる複数形ルールがあります:

  • 英語: 2形式(単数、その他)
  • ロシア語: 3形式(単数、少数、多数)
  • ポーランド語: 3形式(単数、少数、その他)
  • アラビア語: 6形式(ゼロ、単数、双数、少数、多数、その他)

SwiftUI 複数形処理

// Xcode は自動的に複数形バリエーションを作成します
Text("\(count) items")

// カスタムフォーマット付き
Text("\(visitorCount) Recent Visitors")

String Catalog内:

{
  "strings" : {
    "%lld Recent Visitors" : {
      "localizations" : {
        "en" : {
          "variations" : {
            "plural" : {
              "one" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "%lld Recent Visitor"
                }
              },
              "other" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "%lld Recent Visitors"
                }
              }
            }
          }
        }
      }
    }
  }
}

XLIFF エクスポート形式

翻訳用にエクスポートする場合(File → Export Localizations):

レガシー(stringsdict):

<trans-unit id="/%lld Recent Visitors:dict/NSStringLocalizedFormatKey:dict/:string">
    <source>%#@recentVisitors@</source>
</trans-unit>

<trans-unit id="/%lld Recent Visitors:dict/recentVisitors:dict/one:dict/:string">
    <source>%lld Recent Visitor</source>
    <target>%lld Visitante Recente</target>
</trans-unit>

String Catalog(よりクリーン):

<trans-unit id="%lld Recent Visitors|==|plural.one">
    <source>%lld Recent Visitor</source>
    <target>%lld Visitante Recente</target>
</trans-unit>

<trans-unit id="%lld Recent Visitors|==|plural.other">
    <source>%lld Recent Visitors</source>
    <target>%lld Visitantes Recentes</target>
</trans-unit>

複数形変数を使用した置換

// 異なる複数形を持つ複数の変数
let message = String(localized: "\(songCount) songs on \(albumCount) albums")

Xcode は、各変数の複数形に対してバリエーションを作成します:

  • songCount: 単数、その他
  • albumCount: 単数、その他
  • 合計組み合わせ: 2 × 2 = 4 つの翻訳エントリ

パート5: デバイスと幅のバリエーション

デバイス固有の文字列

プラットフォームごとに異なるテキスト:

// 同じコード、デバイスごとに異なる文字列
Text("Bird Food Shop")

String Catalogのバリエーション:

{
  "Bird Food Shop" : {
    "localizations" : {
      "en" : {
        "variations" : {
          "device" : {
            "applewatch" : {
              "stringUnit" : {
                "value" : "Bird Food"
              }
            },
            "other" : {
              "stringUnit" : {
                "value" : "Bird Food Shop"
              }
            }
          }
        }
      }
    }
  }
}

結果:

  • iPhone/iPad: "Bird Food Shop"
  • Apple Watch: "Bird Food"(小画面用に短く)

幅のバリエーション

Dynamic Type やサイズクラスの場合:

Text("Application Settings")

String Catalog は、狭い幅に短いテキストを提供できます。


パート6: RTL サポート

レイアウトのミラーリング

SwiftUI は RTL 言語用にレイアウトを自動的にミラーリングします:

// ✅ アラビア語/ヘブライ語で自動ミラーリング
HStack {
    Image(systemName: "chevron.right")
    Text("Next")
}

// iPhone(英語): [>] Next
// iPhone(アラビア語):  Next [<]

先頭/末尾 vs 左/右

常にセマンティックな方向を使用:

// ✅ 正しい - 自動ミラーリング
.padding(.leading, 16)
.frame(maxWidth: .infinity, alignment: .leading)

// ❌ 間違い - ミラーリングされない
.padding(.left, 16)
.frame(maxWidth: .infinity, alignment: .left)

画像とアイコン

反転すべき/すべきでない画像をマーク:

// ✅ 方向性あり - RTLでミラーリング
Image(systemName: "chevron.forward")

// ✅ 方向性なし - ミラーリングされない
Image(systemName: "star.fill")

// カスタム画像
Image("backButton")
    .flipsForRightToLeftLayoutDirection(true)

RTLモードでのテスト

Xcodeスキーム:

  1. Edit Scheme → Run → Options
  2. Application Language: アラビア語 / ヘブライ語
  3. または: App Language → Right-to-Left Pseudolanguage

シミュレーター: Settings → General → Language & Region → Preferred Language Order

SwiftUIプレビュー:

struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        ContentView()
            .environment(\.layoutDirection, .rightToLeft)
            .environment(\.locale, Locale(identifier: "ar"))
    }
}

パート7: ロケール対応フォーマット

DateFormatter

let formatter = DateFormatter()
formatter.locale = Locale.current  // ✅ 現在のロケールを使用
formatter.dateStyle = .long
formatter.timeStyle = .short

let dateString = formatter.string(from: Date())

// 米国: "January 15, 2024 at 3:30 PM"
// フランス: "15 janvier 2024 à 15:30"
// 日本: "2024年1月15日 15:30"

日付フォーマット文字列をハードコードしない:

// ❌ 間違い - 他のロケールで壊れる
formatter.dateFormat = "MM/dd/yyyy"

// ✅ 正しい - ロケールに適応
formatter.dateStyle = .short

通貨用の NumberFormatter

let formatter = NumberFormatter()
formatter.locale = Locale.current
formatter.numberStyle = .currency

let priceString = formatter.string(from: 29.99)

// 米国: "$29.99"
// 英国: "£29.99"
// 日本: "¥30"(整数に丸める)
// フランス: "29,99 €"(カンマ小数点、記号の前にスペース)

MeasurementFormatter

let distance = Measurement(value: 100, unit: UnitLength.meters)

let formatter = MeasurementFormatter()
formatter.locale = Locale.current

let distanceString = formatter.string(from: distance)

// 米国: "328 ft"(ヤード・ポンド法に変換)
// メートル法の国々: "100 m"

ロケール固有のソート

let names = ["Ångström", "Zebra", "Apple"]

// ✅ ロケール対応ソート
let sorted = names.sorted { (lhs, rhs) in
    lhs.localizedStandardCompare(rhs) == .orderedAscending
}

// スウェーデン: ["Ångström", "Apple", "Zebra"](Å はスウェーデン語で先頭)
// 米国: ["Ångström", "Apple", "Zebra"](Å は A として扱われる)

パート8: App Shortcuts のローカライゼーション

パラメータ付きフレーズ

import AppIntents

struct ShowTopDonutsIntent: AppIntent {
    static var title: LocalizedStringResource = "Show Top Donuts"

    @Parameter(title: "Timeframe")
    var timeframe: Timeframe

    static var parameterSummary: some ParameterSummary {
        Summary("\(.applicationName) Trends for \(\.$timeframe)") {
            \.$timeframe
        }
    }
}

String Catalog はこれらのフレーズを自動的に抽出します。


パート9: 移行とベストプラクティス

.strings / .stringsdict からの移行

Xcode 15+ は移行を自動化します:

  1. Product → Export Localizations... (XLIFFファイルを生成)
  2. 翻訳を String Catalog にインポート
  3. 各言語に .xcstrings ファイルを作成
  4. レガシーファイルを削除

検証:

  • Product → Build でエラーがないことを確認
  • Xcode プレビューですべての言語をテスト
  • 複数形とRTLを検証

ベストプラクティスのまとめ

  1. 常にコメントを含める: 翻訳者にコンテキストを提供
  2. 文字列を連結しない: String(format:) または \(variable) を使用
  3. 意味のあるキーを使用する: 抽象的なキー(WELCOME_MSG)よりも英字テキストを好む
  4. レイアウトにセマンティックな方向を使用する: .leading / .trailing であり .left / .right ではない
  5. 翻訳を初期段階で計画する: アーキテクチャにローカライゼーションを組み込む
  6. すべての言語をテストする: 疑似言語を使用してレイアウトの問題を早期に発見
  7. 日付/数値のフォーマットをハードコードしない: 常に DateFormatter / NumberFormatter を使用
  8. String Catalogの状態を活用する: 翻訳の進行状況を追跡

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

IGTA-Tech/claude-skills-research

Use when implementing SwiftUI animations, understanding VectorArithmetic, using @Animatable macro, choosing between spring and timing curve animations, or debugging animation behavior - comprehensive animation reference from iOS 13 through iOS 26

IGTA-Tech/claude-skills-research

Use when CAAnimation completion handler doesn't fire, spring physics look wrong on device, animation duration mismatches actual time, gesture + animation interaction causes jank, or timing differs between simulator and real hardware - systematic CAAnimation diagnosis with CATransaction patterns, frame rate awareness, and device-specific behavior

IGTA-Tech/claude-skills-research

This skill should be used when comparing two videos to analyze compression results or quality differences. Generates interactive HTML reports with quality metrics (PSNR, SSIM) and frame-by-frame visual comparisons. Triggers when users mention "compare videos", "video quality", "compression analysis", "before/after compression", or request quality assessment of compressed videos.

IGTA-Tech/claude-skills-research

Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use this skill when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failures, 403 errors, or cookie extraction problems.

IGTA-Tech/claude-skills-research

Write high-converting landing page copy using proven frameworks like PAS (Problem-Agitate-Solution), AIDA, and StoryBrand. Creates headlines, value propositions, CTAs, and full page sections optimized for conversion. Use when users need landing page copy, sales page content, or marketing website text.

IGTA-Tech/claude-skills-research

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

IGTA-Tech/claude-skills-research

Download YouTube video transcripts when user provides a YouTube URL or asks to download/get/fetch a transcript from YouTube. Also use when user wants to transcribe or get captions/subtitles from a YouTube video.

関連スキル