ios-localization

dpearson2699/swift-ios-skillsTranslation ServicesAudit passedSnapshot 49e7f5f51323

Summary

Implement, review, or improve localization and internationalization in iOS/macOS apps — String Catalogs (.xcstrings), generated localizable symbols, stable key naming, LocalizedStringKey, LocalizedStringResource, pluralization, FormatStyle for numbers/dates/measurements, right-to-left layout, Dynamic Type, and locale-aware formatting. Use when adding multi-language support, setting up String Catalogs, enabling generated symbols for compile-time-safe localization keys, handling plural forms, formatting dates/numbers/currencies for different locales, testing localizations, or making UI work correctly in RTL languages like Arabic and Hebrew.

SKILL.md

iOS Localization & Internationalization

Localize Apple-platform apps with String Catalogs, modern string types, locale-aware formatting, and right-to-left layout.

String Catalogs and Generated Symbols
String Types -- Decision Guide
String Interpolation in Localized Strings
Pluralization
FormatStyle -- Locale-Aware Formatting
Right-to-Left (RTL) Layout
Common Mistakes
Localization Review Checklist
References

String Catalogs and Generated Symbols

String Catalogs are the recommended Xcode 15+ workflow for new localization work. They keep localizable strings, pluralization rules, and device variations together in an Xcode-managed JSON file with a visual editor. Legacy .strings and .stringsdict files can coexist during migration, but new Swift and SwiftUI code should default to String Catalogs.

How automatic extraction works:

Xcode scans for these patterns on each build:

// SwiftUI -- automatically extracted (LocalizedStringKey)
Text("Welcome back")              // key: "Welcome back"
Label("Settings", systemImage: "gear")
Button("Save") { }
Toggle("Dark Mode", isOn: $dark)

// Programmatic -- automatically extracted
String(localized: "No items found")
LocalizedStringResource("Order placed")

// Plain String: not extracted or localized
let msg = "Hello"

// Generated from key "room_available" in Localizable.xcstrings
Text(.roomAvailable)

// Parameterized key "landmarks_count" with %1$(count)lld
Text(.landmarksCount(count: 42))

// Non-default table "Booking.xcstrings"
Text(.Booking.confirmBookingCta)

Context	Type	Why
SwiftUI view text	`LocalizedStringKey` (implicit)	SwiftUI performs lookup
View models, services, and errors	`String(localized:)`	Resolves to `String` now
App Intents, widgets, deferred system UI	`LocalizedStringResource`	Carries localization until display
Non-user-facing logs and analytics	Plain `String`	No localization needed

Text("Welcome back")
Button("Delete") { deleteItem() }

let title = String(localized: "Welcome back")
let msg = String(localized: "error.network",
                 defaultValue: "Check your internet connection")

struct OrderCoffeeIntent: AppIntent {
    static var title: LocalizedStringResource = "Order Coffee"
}

func showAlert(title: LocalizedStringResource, message: LocalizedStringResource) {
    let resolved = String(localized: title)
}

// English: "Welcome, Alice! You have 3 new messages."
// German:  "Willkommen, Alice! Sie haben 3 neue Nachrichten."
// Japanese: "Alice さん、新しいメッセージが 3 件あります。"
let text = String(localized: "Welcome, \(name)! You have \(count) new messages.")

// Interpolation provides type safety
String(localized: "Score: \(score, format: .number)")
String(localized: "Due: \(date, format: .dateTime.month().day())")

Category	English example	Arabic example
zero	(not used)	0 items
one	1 item	1 item
two	(not used)	2 items (dual)
few	(not used)	3-10 items
many	(not used)	11-99 items
other	2+ items	100+ items

// Code -- single interpolation triggers plural support
Text("\(unreadCount) unread messages")

// String Catalog entries (English):
//   one:   "%lld unread message"
//   other: "%lld unread messages"

// In String Catalog editor, enable "Vary by Device" for a key
// iPhone: "Tap to continue"
// iPad:   "Tap or click to continue"
// Mac:    "Click to continue"

let now = Date.now

// Preset styles
now.formatted(date: .long, time: .shortened)
// US: "January 15, 2026 at 3:30 PM"
// DE: "15. Januar 2026 um 15:30"
// JP: "2026年1月15日 15:30"

// Component-based
now.formatted(.dateTime.month(.wide).day().year())
// US: "January 15, 2026"

// In SwiftUI
Text(now, format: .dateTime.month().day().year())

let count = 1234567
count.formatted()                     // "1,234,567" (US) / "1.234.567" (DE)
count.formatted(.number.precision(.fractionLength(2)))
count.formatted(.percent)             // For 0.85 -> "85%" (US) / "85 %" (FR)

// Currency
let price = Decimal(29.99)
price.formatted(.currency(code: "USD"))  // "$29.99" (US) / "29,99 $US" (FR)
price.formatted(.currency(code: "EUR"))  // "29,99 EUR" (DE)

let distance = Measurement(value: 5, unit: UnitLength.kilometers)
distance.formatted(.measurement(width: .wide))
// US: "3.1 miles" (auto-converts!) / DE: "5 Kilometer"

let temp = Measurement(value: 22, unit: UnitTemperature.celsius)
temp.formatted(.measurement(width: .abbreviated))
// US: "72 F" (auto-converts!) / FR: "22 C"

// Testing RTL in previews
MyView()
    .environment(\.layoutDirection, .rightToLeft)
    .environment(\.locale, Locale(identifier: "ar"))

// Images that should mirror (directional arrows, progress indicators)
Image(systemName: "chevron.right")
    .flipsForRightToLeftLayoutDirection(true)

// Images that should NOT mirror: logos, photos, clocks, music notes

// Forced LTR for specific content (phone numbers, code)
Text("+1 (555) 123-4567")
    .environment(\.layoutDirection, .leftToRight)

// WRONG -- German text is ~30% longer than English
Text(title).frame(width: 120)

// CORRECT
Text(title).fixedSize(horizontal: false, vertical: true)
// Or use VStack/wrapping that accommodates expansion

ios-localization

Summary

SKILL.md

iOS Localization & Internationalization

Contents

String Catalogs and Generated Symbols

String Types -- Decision Guide

LocalizedStringKey (SwiftUI default)

String(localized:) -- Modern NSLocalizedString replacement

LocalizedStringResource -- Pass localization info without resolving

String Interpolation in Localized Strings

Pluralization

Setup in String Catalog

Device Variations

FormatStyle -- Locale-Aware Formatting

Dates

Numbers

Measurements

Right-to-Left (RTL) Layout

What SwiftUI auto-mirrors

What needs manual attention

Layout rules

Common Mistakes

DON'T: Use fixed-width layouts

DO: Use flexible layouts

DON'T: Skip pseudolocalization testing

DO: Test with German (long) and Arabic (RTL) at minimum

Review Checklist

References

Related skills