Localization iOS — Expert Decisions

Expert decision frameworks for localization choices. Claude knows NSLocalizedString and .strings files — this skill provides judgment calls for architecture decisions and cross-language complexity.

Decision Trees

Runtime Language Switching

Do users need in-app language control? ├─ NO (respect system language) │ └─ Standard localization │ NSLocalizedString, let iOS handle it │ Simplest and recommended │ ├─ YES (business requirement) │ └─ Does app restart work? │ ├─ YES → UserDefaults + AppleLanguages │ │ Simpler, more reliable │ └─ NO → Full runtime switching │ Complex: Bundle swizzling or custom lookup │ └─ Single language override only (e.g., always English) └─ Don't localize Bundle.main with no .lproj

The trap: Implementing runtime language switching when system language suffices. It adds complexity and can break third-party SDKs that read system locale.

String Key Architecture

How to structure your keys? ├─ Small app (< 100 strings) │ └─ Flat keys with prefixes │ "login_title", "login_email_placeholder" │ ├─ Medium app │ └─ Hierarchical dot notation │ "auth.login.title", "auth.login.email" │ ├─ Large app with teams │ └─ Feature-based files │ Auth.strings, Profile.strings, etc. │ Each team owns their strings file │ └─ Design system / component library └─ Component-scoped keys "button.primary.title", "input.error.required"

Pluralization Complexity

Which languages do you support? ├─ Western languages only (en, es, fr, de) │ └─ Simple plural rules │ one, other (maybe zero) │ ├─ Slavic languages (ru, pl, uk) │ └─ Complex plural rules │ one, few, many, other │ e.g., Russian: 1 файл, 2 файла, 5 файлов │ ├─ Arabic │ └─ Six plural forms! │ zero, one, two, few, many, other │ MUST use stringsdict │ └─ East Asian (zh, ja, ko) └─ No grammatical plural But may need counters/classifiers

RTL Support Level

Do you support RTL languages? ├─ NO RTL languages planned │ └─ Still use leading/trailing │ Future-proof your layout │ ├─ Arabic only │ └─ Standard RTL support │ layoutDirection + leading/trailing │ Test thoroughly │ ├─ Arabic + Hebrew + Persian │ └─ Each has unique considerations │ Hebrew: different number handling │ Persian: different numerals (۱۲۳) │ └─ Mixed LTR/RTL content └─ Explicit direction per component Force LTR for code, URLs, numbers

NEVER Do

String Management

NEVER concatenate localized strings:

// ❌ Breaks in languages with different word order let message = NSLocalizedString("hello", comment: "") + " " + userName

// German: "Hallo" + " " + "Hans" = "Hallo Hans" ✓ // Japanese: "こんにちは" + " " + "田中" = "こんにちは 田中" ✗ // Should be "田中さん、こんにちは"

// ✅ Use format strings let format = NSLocalizedString("greeting.format", comment: "") let message = String(format: format, userName) // greeting.format = "Hello, %@!" (en) // greeting.format = "%@さん、こんにちは!" (ja)

NEVER embed numbers in translation keys:

// ❌ Doesn't handle plural rules "items.1" = "1 item" "items.2" = "2 items" "items.3" = "3 items" // What about 0? 100? Arabic's 6 forms?

// ✅ Use stringsdict for plurals String.localizedStringWithFormat( NSLocalizedString("items.count", comment: ""), count )

NEVER assume string length:

// ❌ German is ~30% longer than English .frame(width: 100) // "Settings" fits, "Einstellungen" doesn't

// ✅ Use flexible layouts .frame(minWidth: 80) // Or .fixedSize(horizontal: true, vertical: false)

NEVER use left/right in layouts:

// ❌ Breaks in RTL .padding(.left, 16) .frame(alignment: .left)

// ✅ Use leading/trailing .padding(.leading, 16) .frame(alignment: .leading)

Runtime Language

NEVER change AppleLanguages without restart:

// ❌ Partial UI update — inconsistent state UserDefaults.standard.set(["ar"], forKey: "AppleLanguages") // Some views updated, others not. Third-party SDKs broken.

// ✅ Require restart or use custom bundle UserDefaults.standard.set(["ar"], forKey: "AppleLanguages") showRestartRequiredAlert() // User restarts app

NEVER forget to set locale for formatters:

// ❌ Uses device locale, not app's selected language let formatter = DateFormatter() formatter.dateStyle = .medium let date = formatter.string(from: Date()) // Wrong language!

// ✅ Set locale explicitly let formatter = DateFormatter() formatter.locale = Locale(identifier: selectedLanguage.rawValue) formatter.dateStyle = .medium

Pluralization

NEVER use simple if/else for plurals:

// ❌ Fails for Russian, Arabic, etc. func itemsText(_ count: Int) -> String { if count == 1 { return "1 item" } else { return "(count) items" } }

// Russian: 1 товар, 2 товара, 5 товаров, 21 товар, 22 товара... // This requires CLDR plural rules

// ✅ Use stringsdict — iOS handles rules automatically

NEVER hardcode numeral systems:

// ❌ Arabic users may expect Arabic-Indic numerals Text("(count) items") // Shows "5 items" even in Arabic

// ✅ Use NumberFormatter with locale let formatter = NumberFormatter() formatter.locale = Locale(identifier: "ar") formatter.string(from: count as NSNumber) // "٥"

RTL Layouts

NEVER use fixed directional icons:

// ❌ Arrow points wrong way in RTL Image(systemName: "arrow.right")

// ✅ Use semantic icons or flip Image(systemName: "arrow.forward") // Semantic // Or Image(systemName: "arrow.right") .flipsForRightToLeftLayoutDirection(true)

NEVER force layout direction globally when it should be per-component:

// ❌ Phone numbers, code, etc. should stay LTR .environment(.layoutDirection, .rightToLeft)

// ✅ Apply selectively VStack { Text(localizedContent) // Follows RTL

Text(phoneNumber)
    .environment(\.layoutDirection, .leftToRight)  // Always LTR

Text(codeSnippet)
    .environment(\.layoutDirection, .leftToRight)

}

Essential Patterns

Type-Safe Localization with SwiftGen

// swiftgen.yml // strings: // inputs: Resources/en.lproj/Localizable.strings // outputs: // - templateName: structured-swift5 // output: Generated/Strings.swift

// Usage — compile-time safe Text(L10n.Auth.Login.title) Text(L10n.User.greeting(userName)) Text(L10n.Items.count(itemCount))

// Benefits: // - Compiler catches missing keys // - Auto-complete for strings // - Refactoring safe

Stringsdict for Plurals

<!-- en.lproj/Localizable.stringsdict --> <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" ...> <plist version="1.0"> <dict> <key>items.count</key> <dict> <key>NSStringLocalizedFormatKey</key> <string>%#@items@</string> <key>items</key> <dict> <key>NSStringFormatSpecTypeKey</key> <string>NSStringPluralRuleType</string> <key>NSStringFormatValueTypeKey</key> <string>d</string> <key>zero</key> <string>No items</string> <key>one</key> <string>%d item</string> <key>other</key> <string>%d items</string> </dict> </dict> </dict> </plist>

// Usage let text = String.localizedStringWithFormat( NSLocalizedString("items.count", comment: ""), count ) // 0 → "No items" // 1 → "1 item" // 5 → "5 items"

RTL-Aware Layout Helpers

extension View { /// Applies leading alignment that respects RTL func alignLeading() -> some View { self.frame(maxWidth: .infinity, alignment: .leading) }

/// Force LTR for content that shouldn't flip (code, URLs, phone numbers)
func forceLTR() -> some View {
    self.environment(\.layoutDirection, .leftToRight)
}

}

// ContentView struct MessageCell: View { let message: Message

var body: some View {
    VStack(alignment: .leading) {
        Text(message.content)
            .alignLeading()  // Respects RTL

        Text(message.codeSnippet)
            .font(.monospaced(.body)())
            .forceLTR()  // Code always LTR

        Text(message.url)
            .forceLTR()  // URLs always LTR
    }
}

}

Locale-Aware Formatting

struct LocalizedFormatters { let locale: Locale

init(languageCode: String) {
    self.locale = Locale(identifier: languageCode)
}

func formatDate(_ date: Date, style: DateFormatter.Style = .medium) -> String {
    let formatter = DateFormatter()
    formatter.locale = locale
    formatter.dateStyle = style
    return formatter.string(from: date)
}

func formatNumber(_ number: Double) -> String {
    let formatter = NumberFormatter()
    formatter.locale = locale
    formatter.numberStyle = .decimal
    return formatter.string(from: NSNumber(value: number)) ?? "\(number)"
}

func formatCurrency(_ amount: Double, code: String) -> String {
    let formatter = NumberFormatter()
    formatter.locale = locale
    formatter.numberStyle = .currency
    formatter.currencyCode = code
    return formatter.string(from: NSNumber(value: amount)) ?? "\(amount)"
}

}

Quick Reference

Plural Forms by Language

Language Forms Example (1, 2, 5)

English one, other 1 item, 2 items, 5 items

French one, other 1 élément, 2 éléments

Russian one, few, many, other 1 файл, 2 файла, 5 файлов

Arabic zero, one, two, few, many, other 6 forms!

Japanese other only No grammatical plural

RTL Languages

Language Script Direction Numerals

Arabic RTL Arabic-Indic (٠١٢) or Western

Hebrew RTL Western

Persian RTL Extended Arabic (۰۱۲)

Urdu RTL Extended Arabic

String Expansion Guidelines

Source (English) Expansion

1-10 chars +200-300%

11-20 chars +80-100%

21-50 chars +60-80%

51-70 chars +50-60%

70+ chars +30%

Red Flags

Smell Problem Fix

String concatenation Word order varies Format strings

if count == 1 else Wrong plural rules stringsdict

.padding(.left) Breaks RTL .padding(.leading)

DateFormatter without locale Wrong language Set locale explicitly

Runtime language without restart Inconsistent UI Require restart

Fixed frame widths for text Text truncation Flexible layouts

Hardcoded "1, 2, 3" Wrong numeral system NumberFormatter with locale