Localization

Localization

Modern iOS localization using String Catalogs (.xcstrings) for managing translations, plural forms, and locale-aware content. Supports SwiftUI's LocalizedStringKey and String(localized:) APIs.

Reference Loading Guide

ALWAYS load reference files if there is even a small chance the content may be required. It's better to have the context than to miss a pattern or make a mistake.

Core Workflow

1. Create String Catalog in Xcode (File > New > String Catalog) 2. Mark strings with String(localized:comment:) or use SwiftUI's automatic extraction 3. Add plural variants in String Catalog editor where needed 4. Test with pseudo-localization (Scheme > Run > Options > App Language) 5. Export for translation (File > Export Localizations)

Key Patterns

// SwiftUI - automatic localization
Text("Welcome")
Button("Continue") { }

// Explicit localization with context
let title = String(localized: "Settings", comment: "Navigation title")

// Deferred localization for custom views
struct CardView: View {
    let title: LocalizedStringResource
    var body: some View { Text(title) }
}

Build Settings

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

Common Mistakes

1. Forgetting String Catalog in Build Phases — Adding String Catalog but forgetting to check "Localize" in File Inspector means it's not embedded. Always verify in Build Phases > Copy Bundle Resources.

2. Pseudo-localization not tested — Not running your app with pseudo-localization (German/Chinese pseudo-locale) means you miss text overflow and RTL issues. Always test with pseudo-localization before translation.

3. Hardcoded strings anywhere — Even one hardcoded string outside the String Catalog breaks extraction and automation. Use String(localized:) everywhere or use LocalizedStringResource for deferred localization.

4. Context loss in translations — Providing no comment for translators means they guess context and get it wrong. Add comments explaining where the string appears and what it means.

5. RTL layouts not tested — Assuming LTR layout works for RTL languages (Arabic, Hebrew) fails miserably. Test with system language set to Arabic and verify semantic directions are used.

Locale-Aware Formatting

Proper formatting of dates, numbers, and currencies adapts automatically to the user's locale. Never hardcode format patterns.

Date Formatting

DateFormatter (Foundation)

let formatter = DateFormatter()
formatter.locale = Locale.current  // Always use current locale
formatter.dateStyle = .long
formatter.timeStyle = .short

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

// US: "January 15, 2024 at 3:30 PM"
// France: "15 janvier 2024 a 15:30"
// Japan: "2024/1/15 15:30"
// Germany: "15. Januar 2024 um 15:30"

FormatStyle (iOS 15+)

Modern, type-safe formatting:

let date = Date()

// Date styles
date.formatted(date: .long, time: .shortened)
// US: "January 15, 2024 at 3:30 PM"

date.formatted(date: .abbreviated, time: .omitted)
// US: "Jan 15, 2024"

// Custom components
date.formatted(.dateTime.month().day().year())
// US: "Jan 15, 2024"

// Relative dates
date.formatted(.relative(presentation: .named))
// "yesterday", "tomorrow", "in 2 days"

Common Mistakes

// WRONG - US-only format, breaks in other locales
let formatter = DateFormatter()
formatter.dateFormat = "MM/dd/yyyy"

// CORRECT - adapts to locale
formatter.dateStyle = .short

// WRONG - hardcoded separator
let dateStr = "\(month)/\(day)/\(year)"

// CORRECT - use formatter
let dateStr = date.formatted(date: .numeric, time: .omitted)

Number Formatting

NumberFormatter

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

let number = 1234567.89
formatter.string(from: NSNumber(value: number))

// US: "1,234,567.89"
// Germany: "1.234.567,89"
// France: "1 234 567,89"

FormatStyle (iOS 15+)

let value = 1234567.89

// Decimal
value.formatted(.number)
// US: "1,234,567.89"

// With precision
value.formatted(.number.precision(.fractionLength(0...2)))

// Percentage
0.856.formatted(.percent)
// US: "85.6%"
// Arabic: "86%"

Currency Formatting

NumberFormatter

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

let price = 29.99
formatter.string(from: NSNumber(value: price))

// US: "$29.99"
// UK: "GBP29.99" or "PS29.99"
// Japan: "JPY30" (rounded, no decimals)
// France: "29,99 EUR" (comma decimal, space before symbol)

FormatStyle (iOS 15+)

let price = 29.99

// User's currency
price.formatted(.currency(code: "USD"))
// US: "$29.99"

// Specific currency
price.formatted(.currency(code: "EUR"))
// "$29.99" displayed as "EUR29.99"

// Narrow symbol
price.formatted(.currency(code: "USD").presentation(.narrow))
// "$29.99" instead of "US$29.99"

Decimal vs Currency

// Currency amounts should use Decimal, not Double
let price = Decimal(string: "29.99")!

let formatter = NumberFormatter()
formatter.numberStyle = .currency
formatter.string(from: price as NSDecimalNumber)

Measurement Formatting

MeasurementFormatter

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

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

formatter.string(from: distance)

// US: "328 ft" (converts to imperial)
// Metric countries: "100 m"

FormatStyle (iOS 15+)

let distance = Measurement(value: 5, unit: UnitLength.kilometers)

// Natural units for locale
distance.formatted(.measurement(width: .abbreviated))
// US: "3.1 mi"
// Metric: "5 km"

// Force specific unit
distance.formatted(.measurement(width: .abbreviated, usage: .asProvided))
// Always: "5 km"

List Formatting

ListFormatter

let items = ["apples", "oranges", "bananas"]

let formatter = ListFormatter()
formatter.locale = Locale.current
formatter.string(from: items)

// English: "apples, oranges, and bananas"
// Spanish: "manzanas, naranjas y platanos"
// Chinese: "apples, oranges and bananas"

FormatStyle (iOS 15+)

let names = ["Alice", "Bob", "Charlie"]

names.formatted(.list(type: .and))
// "Alice, Bob, and Charlie"

names.formatted(.list(type: .or))
// "Alice, Bob, or Charlie"

Person Name Formatting

var components = PersonNameComponents()
components.givenName = "John"
components.familyName = "Smith"

let formatter = PersonNameComponentsFormatter()
formatter.style = .default
formatter.string(from: components)

// Western: "John Smith"
// Chinese/Japanese/Korean: "Smith John" (family name first)

Locale-Specific Sorting

let names = ["Angstrom", "Zebra", "Apple", "aardvark"]

// Locale-aware sort
let sorted = names.sorted { (lhs, rhs) in
    lhs.localizedStandardCompare(rhs) == .orderedAscending
}

// Case-insensitive, locale-aware
let sorted2 = names.sorted {
    $0.localizedCaseInsensitiveCompare($1) == .orderedAscending
}

SwiftUI Integration

Text with Formatting

struct PriceView: View {
    let price: Decimal

    var body: some View {
        Text(price, format: .currency(code: "USD"))
    }
}

struct DateView: View {
    let date: Date

    var body: some View {
        Text(date, format: .dateTime.month().day().year())
    }
}

struct CountView: View {
    let count: Int

    var body: some View {
        Text(count, format: .number)
    }
}

Environment Locale

struct FormattedView: View {
    @Environment(\.locale) var locale

    var body: some View {
        // Format using environment locale
        Text(Date(), format: .dateTime.locale(locale))
    }
}

// Preview with specific locale
struct FormattedView_Previews: PreviewProvider {
    static var previews: some View {
        FormattedView()
            .environment(\.locale, Locale(identifier: "fr_FR"))
    }
}

Best Practices

1. Never hardcode format strings - Use style-based formatting 2. Always use Locale.current - Unless explicitly overriding 3. Use Decimal for money - Avoids floating-point errors 4. Test multiple locales - US, Germany, Japan, Arabic cover most edge cases 5. Prefer FormatStyle - Modern, type-safe, SwiftUI-friendly

Testing Locales

// Unit test with specific locale
func testGermanCurrency() {
    let formatter = NumberFormatter()
    formatter.locale = Locale(identifier: "de_DE")
    formatter.numberStyle = .currency

    let result = formatter.string(from: 1234.56)
    XCTAssertEqual(result, "1.234,56 EUR")
}

Scheme testing: 1. Edit Scheme > Run > Options 2. Application Region > Choose region 3. Run and verify formatting

Pluralization

Handling plural forms correctly is critical for proper localization. Different languages have vastly different plural rules.

Plural Categories by Language

SwiftUI Plural Handling

Xcode automatically creates plural variations when you interpolate numbers:

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

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

In the String Catalog, Xcode generates entries for each plural form:

String Catalog JSON:

{
  "%lld items": {
    "localizations": {
      "en": {
        "variations": {
          "plural": {
            "one": {
              "stringUnit": {
                "state": "translated",
                "value": "%lld item"
              }
            },
            "other": {
              "stringUnit": {
                "state": "translated",
                "value": "%lld items"
              }
            }
          }
        }
      }
    }
  }
}

Multiple Variables

When strings have multiple numeric placeholders, Xcode creates variations for each:

let message = String(localized: "\(songCount) songs on \(albumCount) albums")

Combinations generated:

• songCount=one, albumCount=one: "1 song on 1 album"
• songCount=one, albumCount=other: "1 song on 3 albums"
• songCount=other, albumCount=one: "5 songs on 1 album"
• songCount=other, albumCount=other: "5 songs on 3 albums"

Total: 2 x 2 = 4 translation entries for English.

Working with the String Catalog Editor

1. Select the string in String Catalog 2. Click "Vary by Plural" in the inspector 3. Add translations for each required form

Important: Always provide all required plural forms for each language. Missing forms fall back to "other".

Legacy stringsdict Format

Before String Catalogs, plurals used .stringsdict files:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>%lld items</key>
    <dict>
        <key>NSStringLocalizedFormatKey</key>
        <string>%#@items@</string>
        <key>items</key>
        <dict>
            <key>NSStringFormatSpecTypeKey</key>
            <string>NSStringPluralRuleType</string>
            <key>NSStringFormatValueTypeKey</key>
            <string>lld</string>
            <key>one</key>
            <string>%lld item</string>
            <key>other</key>
            <string>%lld items</string>
        </dict>
    </dict>
</dict>
</plist>

Migration: Convert .stringsdict to String Catalog using Editor > Convert to String Catalog. Plural variations are preserved.

Format Specifiers

Code Patterns

Explicit Plural Handling

// Let String Catalog handle plurals
let itemLabel = String(localized: "\(itemCount) items",
                       comment: "Shopping cart item count")

// For complex cases, use AttributedString
let styled = AttributedString(localized: "You have **\(count)** items")

Avoiding Plural Mistakes

// WRONG - grammatically incorrect in most languages
Text("\(count) item(s)")

// WRONG - hardcoded English logic
Text(count == 1 ? "1 item" : "\(count) items")

// CORRECT - let String Catalog handle it
Text("\(count) items")

Zero Special Case

Some languages have special "zero" form:

// In English, we might want special zero handling
// String Catalog can provide device variations
Text("\(count) notifications")

// Zero: "No notifications"
// One: "1 notification"
// Other: "5 notifications"

Configure in String Catalog by adding "zero" variation.

XLIFF Export

When exporting for translation, plural forms appear cleanly:

<trans-unit id="%lld items|==|plural.one">
    <source>%lld item</source>
    <target>%lld elemento</target>
</trans-unit>

<trans-unit id="%lld items|==|plural.other">
    <source>%lld items</source>
    <target>%lld elementos</target>
</trans-unit>

Testing Plurals

Scheme Options: 1. Edit Scheme > Run > Options 2. App Language > Choose target language

Preview Testing:

struct ItemCountView_Previews: PreviewProvider {
    static var previews: some View {
        Group {
            ItemCountView(count: 0)
            ItemCountView(count: 1)
            ItemCountView(count: 2)
            ItemCountView(count: 5)
            ItemCountView(count: 21)  // Tests Russian "one" form
        }
    }
}

Troubleshooting

Plural forms not appearing: 1. Ensure string uses interpolation: "\(count) items" 2. Build project to extract strings 3. Check "Vary by Plural" is enabled in String Catalog

Wrong plural form selected:

• Verify you're testing with correct locale
• Check format specifier matches variable type
• Russian/Polish have complex rules - test with various numbers

Stringsdict not converting:

• Ensure .strings and .stringsdict have same base name
• Both files must be in same location
• Convert together for merged result

Right-to-Left (RTL) Support

Supporting RTL languages (Arabic, Hebrew, Persian, Urdu) is essential for global apps. SwiftUI handles most mirroring automatically, but requires semantic layout choices.

Automatic Layout Mirroring

SwiftUI automatically mirrors layouts for RTL languages:

// Automatically mirrors for Arabic/Hebrew
HStack {
    Image(systemName: "chevron.right")
    Text("Next")
}

// LTR (English): [>] Next
// RTL (Arabic):  Next [<]

Leading/Trailing vs Left/Right

Always use semantic directions that adapt to layout direction:

// CORRECT - mirrors automatically
.padding(.leading, 16)
.padding(.trailing, 8)
.frame(maxWidth: .infinity, alignment: .leading)

// WRONG - doesn't mirror, breaks RTL
.padding(.left, 16)
.padding(.right, 8)
.frame(maxWidth: .infinity, alignment: .left)

Alignment

// CORRECT
VStack(alignment: .leading) {
    Text("Title")
    Text("Subtitle")
}

// WRONG
VStack(alignment: .left) {  // Doesn't exist, but conceptually wrong
    Text("Title")
}

Edge Insets

// CORRECT - semantic edges
.padding(EdgeInsets(top: 8, leading: 16, bottom: 8, trailing: 16))

// For non-mirroring needs (rare)
.padding(EdgeInsets(top: 8, leading: 16, bottom: 8, trailing: 16))
    .environment(\.layoutDirection, .leftToRight)

Images and Icons

SF Symbols

SF Symbols handle directionality automatically:

// Directional - mirrors for RTL
Image(systemName: "chevron.forward")  // Points right in LTR, left in RTL
Image(systemName: "chevron.backward") // Points left in LTR, right in RTL

// Non-directional - never mirrors
Image(systemName: "star.fill")
Image(systemName: "heart.fill")

Custom Images

Mark images that should flip:

// Image should mirror
Image("backArrow")
    .flipsForRightToLeftLayoutDirection(true)

// Image should NOT mirror (logos, photos)
Image("companyLogo")
    .flipsForRightToLeftLayoutDirection(false)  // Default

Asset Catalog Settings

In Asset Catalog: 1. Select image asset 2. Attributes Inspector > Direction 3. Choose: "Fixed" (never flip) or "Mirrors" (flip for RTL)

Text Alignment

// Adapts to layout direction
Text("Hello")
    .multilineTextAlignment(.leading)  // Left in LTR, right in RTL

// Force specific alignment (rare)
Text("Code sample")
    .multilineTextAlignment(.trailing)

Mixed Content

// Numbers and punctuation in RTL text
Text("Price: $99.99")  // System handles bidirectional text

// Force LTR for specific content
Text("\u{200E}$99.99")  // Left-to-right mark

Detecting Layout Direction

Environment Value

struct DirectionalView: View {
    @Environment(\.layoutDirection) var layoutDirection

    var body: some View {
        HStack {
            if layoutDirection == .rightToLeft {
                trailingContent
                Spacer()
                leadingContent
            } else {
                leadingContent
                Spacer()
                trailingContent
            }
        }
    }
}

Conditional Modifiers

extension View {
    @ViewBuilder
    func rtlAware() -> some View {
        self.environment(\.layoutDirection,
            Locale.current.language.characterDirection == .rightToLeft
                ? .rightToLeft
                : .leftToRight)
    }
}

Scroll Views

// Automatically adapts scroll direction
ScrollView(.horizontal) {
    HStack {
        ForEach(items) { item in
            ItemView(item: item)
        }
    }
}
// LTR: scrolls left-to-right
// RTL: scrolls right-to-left

Lists and Navigation

// List disclosure indicators mirror automatically
List(items) { item in
    NavigationLink(destination: DetailView(item: item)) {
        Text(item.name)
    }
}
// LTR: Text [>]
// RTL: [<] Text

Testing RTL Layouts

Xcode Scheme

1. Edit Scheme > Run > Options 2. Application Language > Arabic or Hebrew 3. OR: App Language > Right-to-Left Pseudolanguage

SwiftUI Preview

struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        Group {
            ContentView()
                .previewDisplayName("LTR")

            ContentView()
                .environment(\.layoutDirection, .rightToLeft)
                .environment(\.locale, Locale(identifier: "ar"))
                .previewDisplayName("RTL")
        }
    }
}

Simulator

Settings > General > Language & Region > Preferred Language Order > Add Arabic/Hebrew

UIKit Considerations

UIView

// Check effective layout direction
if view.effectiveUserInterfaceLayoutDirection == .rightToLeft {
    // RTL-specific adjustments
}

// Semantic content attribute
view.semanticContentAttribute = .forceLeftToRight  // Override mirroring
view.semanticContentAttribute = .unspecified       // Follow system

Auto Layout

// CORRECT - semantic constraints
leadingAnchor.constraint(equalTo: other.leadingAnchor)
trailingAnchor.constraint(equalTo: other.trailingAnchor)

// WRONG - absolute constraints
leftAnchor.constraint(equalTo: other.leftAnchor)
rightAnchor.constraint(equalTo: other.rightAnchor)

Common Patterns

Progress Indicators

// Progress should typically NOT mirror
ProgressView(value: 0.7)
    .environment(\.layoutDirection, .leftToRight)

Media Controls

// Playback controls typically don't mirror
HStack {
    Button(action: rewind) {
        Image(systemName: "backward.fill")
    }
    Button(action: playPause) {
        Image(systemName: "play.fill")
    }
    Button(action: forward) {
        Image(systemName: "forward.fill")
    }
}
.environment(\.layoutDirection, .leftToRight)

Form Layouts

// Forms mirror correctly with semantic alignment
Form {
    HStack {
        Text("Email")
        Spacer()
        TextField("email@example.com", text: $email)
            .multilineTextAlignment(.trailing)
    }
}

Best Practices

1. Use leading/trailing - Never left/right for layout 2. Test with RTL pseudolanguage - Catches issues without translation 3. Use directional SF Symbols - chevron.forward, not chevron.right 4. Don't mirror logos and photos - Only directional UI elements 5. Test bidirectional text - Mix of Arabic/Hebrew with numbers 6. Consider reading order - Important content should be at "start"

Troubleshooting

Layout not mirroring:

• Check for hardcoded .left/.right usage
• Verify parent views aren't forcing LTR
• Check asset catalog Direction settings

Text alignment wrong:

• Use .leading/.trailing, not .left/.right
• Check multilineTextAlignment setting

Images not flipping:

• Add .flipsForRightToLeftLayoutDirection(true)
• Or configure in Asset Catalog

Scroll direction wrong:

• ScrollView mirrors automatically
• Check if parent overrides layoutDirection

String Catalogs

Xcode 15+ unified format for managing app localization. Replaces legacy .strings and .stringsdict files with a single JSON-based format.

Creating a String Catalog

Method 1: Xcode Navigator 1. File > New > File 2. Choose "String Catalog" 3. Name it Localizable.xcstrings 4. Add to target

Method 2: Automatic Extraction Build the project - Xcode extracts strings from:

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

SwiftUI Localization

LocalizedStringKey (Automatic)

// Automatically localizable - Xcode extracts these
Text("Welcome to the App!")
Label("Shopping Cart", systemImage: "cart")
Button("Checkout") { }

String(localized:) with Comments

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

// With translator comment (recommended)
let title = String(localized: "Welcome",
                   comment: "Main screen greeting")

// With custom table
let title = String(localized: "Welcome",
                   table: "Onboarding",
                   comment: "First launch greeting")

// With default value (key != English text)
let title = String(localized: "WELCOME_TITLE",
                   defaultValue: "Welcome to the App!",
                   comment: "Main screen title")

LocalizedStringResource (Deferred Lookup)

Use when passing localizable strings to custom views:

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

    var body: some View {
        VStack {
            Text(title)      // Resolved at render time
            Text(subtitle)
        }
    }
}

// Usage
CardView(
    title: "Recent Purchases",
    subtitle: "Items from the past week"
)

AttributedString with Markdown

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

String Catalog Structure

Each entry contains:

• Key: Unique identifier (default: the English string)
• Default Value: Fallback if translation missing
• Comment: Context for translators
• State: New, Needs Review, Reviewed, Stale

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

UIKit & Foundation

NSLocalizedString

let title = NSLocalizedString("Recent Purchases",
                              comment: "Section header")

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

Bundle.localizedString

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

Migration from Legacy Files

Converting .strings to .xcstrings

1. Select .strings file in Navigator 2. Editor > Convert to String Catalog 3. Xcode creates .xcstrings preserving translations

Gradual Migration

• Keep legacy .strings for old code initially
• New code uses String Catalogs
• Both work together - Xcode checks both
• Convert one table at a time

Common Mistakes

// WRONG - not localizable
let title = "Settings"

// CORRECT - localizable
let title = String(localized: "Settings")

// WRONG - concatenation breaks word order
let msg = String(localized: "You have") + " \(count) " + String(localized: "items")

// CORRECT - single string with substitution
let msg = String(localized: "You have \(count) items")

// WRONG - no context for translator
String(localized: "Confirm")

// CORRECT - clear context
String(localized: "Confirm", comment: "Button to confirm deletion")

Troubleshooting

Strings not appearing in catalog: 1. Build Settings > "Use Compiler to Extract Swift Strings" > Yes 2. Clean Build Folder (Cmd+Shift+K) 3. Build project

Translations not showing: 1. Project > Info > Localizations > Add language 2. Check string isn't marked "Stale"