axiom-localization

Localization & Internationalization

Comprehensive guide to app localization using String Catalogs. Apple Design Award Inclusivity winners always support multiple languages with excellent RTL (Right-to-Left) support.

Overview

String Catalogs (.xcstrings) are Xcode 15's unified format for managing app localization. They replace legacy .strings and .stringsdict files with a single JSON-based format that's easier to maintain, diff, and integrate with translation workflows.

This skill covers String Catalogs, SwiftUI/UIKit localization APIs, plural handling, RTL support, locale-aware formatting, and migration strategies from legacy formats.

When to Use This Skill

• Setting up String Catalogs in Xcode 15+
• Localizing SwiftUI and UIKit apps
• Handling plural forms correctly (critical for many languages)
• Supporting RTL languages (Arabic, Hebrew)
• Formatting dates, numbers, and currencies by locale
• Migrating from legacy .strings/.stringsdict files
• Preparing App Shortcuts and App Intents for localization
• Debugging missing translations or incorrect plural forms

System Requirements

• Xcode 15+ for String Catalogs (.xcstrings)
• Xcode 26+ for automatic symbol generation, #bundle macro, and AI-powered comment generation
• iOS 15+ for LocalizedStringResource
• iOS 16+ for App Shortcuts localization
• Earlier iOS versions use legacy .strings files

---

Part 1: String Catalogs (WWDC 2023/10155)

Creating a String Catalog

Method 1: Xcode Navigator

1. File → New → File
2. Choose "String Catalog"
3. Name it (e.g., Localizable.xcstrings)
4. Add to target

Method 2: Automatic Extraction

Xcode 15 can automatically extract strings from:

• SwiftUI views (string literals in Text, Label, Button)
• Swift code (String(localized:))
• Objective-C (NSLocalizedString)
• C (CFCopyLocalizedString)
• Interface Builder files (.storyboard, .xib)
• Info.plist values
• App Shortcuts phrases

Build Settings Required:

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

String Catalog Structure

Each entry has:

• Key: Unique identifier (default: the English string)
• Default Value: Fallback if translation missing
• Comment: Context for translators
• String Table: Organization container (default: "Localizable")

Example .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"
}

Translation States

Xcode tracks state for each translation:

• New (⚪) - String hasn't been translated yet
• Needs Review (🟡) - Source changed, translation may be outdated
• Reviewed (✅) - Translation approved and current
• Stale (🔴) - String no longer found in source code

Workflow:

1. Developer adds string → New
2. Translator adds translation → Reviewed
3. Developer changes source → Needs Review
4. Translator updates → Reviewed
5. Developer removes code → Stale

---

Part 2: SwiftUI Localization

LocalizedStringKey (Automatic)

SwiftUI views with String parameters automatically support localization:

// ✅ Automatically localizable
Text("Welcome to WWDC!")
Label("Thanks for shopping with us!", systemImage: "bag")
Button("Checkout") { }

// Xcode extracts these strings to String Catalog

How it works: SwiftUI uses LocalizedStringKey internally, which looks up strings in String Catalogs.

String(localized:) with Comments

For explicit localization in Swift code:

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

// With comment for translators
let title = String(localized: "Welcome to WWDC!",
                   comment: "Notification banner title")

// With custom table
let title = String(localized: "Welcome to WWDC!",
                   table: "WWDCNotifications",
                   comment: "Notification banner title")

// With default value (key ≠ English text)
let title = String(localized: "WWDC_NOTIFICATION_TITLE",
                   defaultValue: "Welcome to WWDC!",
                   comment: "Notification banner title")

Best practice: Always include comment to give translators context.

LocalizedStringResource (Deferred Localization)

For passing localizable strings to other functions:

import Foundation

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

    var body: some View {
        ZStack {
            RoundedRectangle(cornerRadius: 10.0)
            VStack {
                Text(title)      // Resolved at render time
                Text(subtitle)
            }
            .padding()
        }
    }
}

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

Key difference: LocalizedStringResource defers lookup until used, allowing custom views to be fully localizable.

AttributedString with Markdown

// Markdown formatting is preserved across localizations
let subtitle = AttributedString(localized: "**Bold** and _italic_ text")

---

Part 3: UIKit & Foundation

NSLocalizedString Macro

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

// With table
let title = NSLocalizedString("Recent Purchases",
                             tableName: "Shopping",
                             comment: "Button Title")

// With bundle
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")

Custom Macros

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

Info.plist Localization

Localize app name, permissions, etc.:

1. Select Info.plist
2. Editor → Add Localization
3. Create InfoPlist.strings for each language:

// InfoPlist.strings (Spanish)
"CFBundleName" = "Mi Aplicación";
"NSCameraUsageDescription" = "La app necesita acceso a la cámara para tomar fotos.";

---

Part 4: Pluralization

Different languages have different plural rules:

• English: 2 forms (one, other)
• Russian: 3 forms (one, few, many)
• Polish: 3 forms (one, few, other)
• Arabic: 6 forms (zero, one, two, few, many, other)

SwiftUI Plural Handling

// Xcode automatically creates plural variations
Text("\(count) items")

// With custom formatting
Text("\(visitorCount) Recent Visitors")

In 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 Export Format

When exporting for translation (File → Export Localizations):

Legacy (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 (cleaner):

<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>

Substitutions with Plural Variables

// Multiple variables with different plural forms
let message = String(localized: "\(songCount) songs on \(albumCount) albums")

Xcode creates variations for each variable's plural form:

• songCount: one, other
• albumCount: one, other
• Total combinations: 2 × 2 = 4 translation entries

---

Part 5: Device & Width Variations

Device-Specific Strings

Different text for different platforms:

// Same code, different strings per device
Text("Bird Food Shop")

String Catalog variations:

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

Result:

• iPhone/iPad: "Bird Food Shop"
• Apple Watch: "Bird Food" (shorter for small screen)

Width Variations

For dynamic type and size classes:

Text("Application Settings")

String Catalog can provide shorter text for narr

---

Content truncated.