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(
how to use axiom-localization
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use axiom-localization on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add axiom-localization
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/charleswiltgen/axiom --skill axiom-localizationcopy
The skills CLI fetches axiom-localization from GitHub repository charleswiltgen/axiom and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/axiom-localization
Reload or restart Cursor to activate axiom-localization. Access the skill through slash commands (e.g., /axiom-localization) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?