ios-localization

iOS Localization & Internationalization

Localize Apple-platform applications using String Catalogs (.xcstrings), compiler-generated symbols, locale-aware FormatStyle, and right-to-left (RTL) layout adaptation. Targets Swift 6.3 / iOS 26+.

Contents

• String Catalogs (.xcstrings)
• String Types: Key vs Resource
• Pluralization & Variations
• FormatStyle & Locales
• Right-to-Left (RTL) Layout
• Common Mistakes
• Review Checklist
• References

String Catalogs (.xcstrings)

String Catalogs are the standard format for Xcode localization. Xcode automatically extracts localizable strings from source code on every build:

// Automatically extracted as LocalizedStringKey in SwiftUI
Text("Welcome back")
Button("Save Changes") { }
Label("Account Settings", systemImage: "person.crop.circle")

For non-view code, use generated symbols or String(localized:):

// Modern type-safe localized string
let message = String(localized: "order_confirmation_title", defaultValue: "Order Confirmed")

String Types: Key vs Resource

• LocalizedStringKey: Used across SwiftUI views (Text, Button). Evaluated lazily at view render time.
• LocalizedStringResource: Decoupled from SwiftUI. Ideal for passing localized strings across view models, models, or App Intents.
• String(localized:): Immediately materializes the localized String using the current locale.

Pluralization & Variations

String Catalogs support Unicode plural rules (zero, one, two, few, many, other) and device-specific variations (iPhone, iPad, Mac) in the visual catalog editor without complex .stringsdict files:

// Single integer interpolation triggers plural variant support in String Catalogs
Text("\(unreadCount) unread messages")

FormatStyle & Locales

Never format currency, numbers, or dates with manual string concatenation. Always use FormatStyle:

// Currency formatting adhering to user locale
let priceString = amount.formatted(.currency(code: "USD"))

// Date and relative time formatting
let dateString = eventDate.formatted(date: .abbreviated, time: .shortened)
let relativeString = eventDate.formatted(.relative(presentation: .named))

Right-to-Left (RTL) Layout

• Use leading/trailing layout constraints rather than absolute left/right.
• Directional SF Symbols mirror automatically; set .imageScale or disable mirroring only when representing physical hardware orientation.

Common Mistakes

• String concatenation for localized sentences: Concatenating strings breaks syntax across languages. Use format specifiers with positional arguments (%1$@).
• Hardcoding date or number formatting: Manual decimal or comma placement breaks in non-US locales. Use FormatStyle.
• Using left/right alignment: Hardcoded left/right alignments do not flip in Arabic/Hebrew RTL layouts. Use leading/trailing.
• Eager localization in static constants: Initializing String(localized:) in static properties pins the language at launch, failing when the user switches language dynamically.
• Ignoring pluralization variations: Hardcoding s for counts fails across languages with complex plural rules (e.g. Russian, Arabic).

Review Checklist

• String Catalogs (.xcstrings) used for all new string localization
• LocalizedStringResource used when passing localized strings from model layers
• Numeric, date, and currency values formatted via Foundation FormatStyle
• Layout constraints and padding use leading and trailing
• Inflection and plural rules configured in String Catalogs

References

• FormatStyle patterns: references/formatstyle-locale.md
• String Catalogs guide: references/string-catalogs.md