XCStrings Format Overview

String Catalogs (.xcstrings) are JSON files that store all your app's localizable strings. Introduced in Xcode 15, they consolidate all languages, plurals, and device variations into one file.

File Structure#

An .xcstrings file has this basic structure:

{
  "sourceLanguage": "en",
  "version": "1.0",
  "strings": {
    "welcome_message": {
      "extractionState": "manual",
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "Welcome to the app!"
          }
        },
        "de": {
          "stringUnit": {
            "state": "translated",
            "value": "Willkommen in der App!"
          }
        }
      }
    }
  }
}

Key Properties#

How Xcode Manages String Catalogs#

When you build your project, Xcode:

1. Extracts strings from Text(), String(localized:), and other APIs
2. Adds new keys with state "new"
3. Marks strings as "stale" if the source text changes
4. Preserves existing translations

Next Steps#

• Translation States — Understanding new, translated, stale, and needs_review
• Pluralization — Handling "1 item" vs "5 items"
• Device Variations — Platform-specific text