Apple String Catalogs (.xcstrings) Import

Azbox supports Apple String Catalogs (.xcstrings), the modern localization format introduced in Xcode 15 for iOS, macOS, watchOS, and tvOS applications.

What are String Catalogs?

String Catalogs (.xcstrings) are Apple's modern replacement for the legacy .strings and .stringsdict files. They consolidate all localizations into a single JSON-based file, making translation management much easier.

Key benefits:

• ✅ All languages in one file
• ✅ JSON-based (easy to parse)
• ✅ Built-in pluralization support
• ✅ Automatic extraction from Swift code
• ✅ Visual editor in Xcode

File Structure

An .xcstrings file is a JSON document:

Localizable.xcstrings

{
  "sourceLanguage": "en",
  "version": "1.0",
  "strings": {
    "welcome_message": {
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "Welcome to our app!"
          }
        },
        "es": {
          "stringUnit": {
            "state": "translated",
            "value": "¡Bienvenido a nuestra app!"
          }
        }
      }
    }
  }
}

Structure Breakdown

Field	Description
sourceLanguage	Base language code (e.g., en)
version	File format version
strings	Object containing all translation keys
localizations	Translations for each language
stringUnit	Contains the actual translation value
state	Translation state: translated, needs_review, new

Format Features

Simple Strings

{
  "strings": {
    "login_button": {
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "Log In"
          }
        }
      }
    }
  }
}

String Interpolation

Variables use %@ (string), %d (integer), %lld (long), %f (float):

{
  "strings": {
    "greeting": {
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "Hello, %@!"
          }
        },
        "es": {
          "stringUnit": {
            "state": "translated",
            "value": "¡Hola, %@!"
          }
        }
      }
    }
  }
}

Pluralization

{
  "strings": {
    "items_count": {
      "localizations": {
        "en": {
          "variations": {
            "plural": {
              "zero": {
                "stringUnit": {
                  "state": "translated",
                  "value": "No items"
                }
              },
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "1 item"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld items"
                }
              }
            }
          }
        }
      }
    }
  }
}

Device Variations

{
  "strings": {
    "tap_continue": {
      "localizations": {
        "en": {
          "variations": {
            "device": {
              "iphone": {
                "stringUnit": {
                  "state": "translated",
                  "value": "Tap to continue"
                }
              },
              "mac": {
                "stringUnit": {
                  "state": "translated",
                  "value": "Click to continue"
                }
              }
            }
          }
        }
      }
    }
  }
}

Complete Example

Localizable.xcstrings

{
  "sourceLanguage": "en",
  "version": "1.0",
  "strings": {
    "app_name": {
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "My App"
          }
        },
        "es": {
          "stringUnit": {
            "state": "translated",
            "value": "Mi App"
          }
        },
        "fr": {
          "stringUnit": {
            "state": "translated",
            "value": "Mon App"
          }
        }
      }
    },
    "welcome_user": {
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "Welcome, %@!"
          }
        },
        "es": {
          "stringUnit": {
            "state": "translated",
            "value": "¡Bienvenido, %@!"
          }
        },
        "fr": {
          "stringUnit": {
            "state": "translated",
            "value": "Bienvenue, %@ !"
          }
        }
      }
    },
    "photos_count": {
      "localizations": {
        "en": {
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld photo"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld photos"
                }
              }
            }
          }
        },
        "es": {
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld foto"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld fotos"
                }
              }
            }
          }
        }
      }
    }
  }
}

How to Import in Azbox

Step 1: Open Import Dialog

Click Import in your project dashboard.

Step 2: Select Format

Choose Apple (.xcstrings) from the dropdown.

Step 3: Select Target Language

Choose which language from the xcstrings file you want to import.

Multi-language Files

xcstrings files contain all languages in one file. Select one language per import, then repeat for other languages.

Step 4: Import

Click Import and select your .xcstrings file.

Step 5: Review Results

Check the import summary:

• ✅ Keywords imported
• ⚠️ Empty translations skipped
• ❌ Parsing errors (if any)

What Gets Imported

Content	Imported	Notes
Simple strings	✅ Yes	Direct value extraction
Interpolation (%@)	✅ Yes	Preserved as-is
Plurals	✅ Yes	other variant imported
Device variations	⚠️ Partial	First variant imported
Comments	❌ No	Not transferred

Usage in Swift

// Simple string
Text("welcome_message")

// With interpolation
Text("welcome_user \(userName)")

// Pluralization
Text("photos_count \(count)")

SwiftUI and UIKit automatically use Localizable.xcstrings when you use String(localized:) or SwiftUI Text().

Legacy Formats

Deprecated Formats

Azbox marks .strings and .stringsdict as deprecated. Apple recommends migrating to .xcstrings for new projects.

.strings (Legacy)

The old plain-text format:

/* Comment */
"key" = "value";
"greeting" = "Hello, World!";

.stringsdict (Legacy)

XML-based format for plurals:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "...">
<plist version="1.0">
<dict>
  <key>items_count</key>
  <dict>
    <key>NSStringLocalizedFormatKey</key>
    <string>%#@items@</string>
    <key>items</key>
    <dict>
      <key>NSStringFormatSpecTypeKey</key>
      <string>NSStringPluralRuleType</string>
      <key>one</key>
      <string>%d item</string>
      <key>other</key>
      <string>%d items</string>
    </dict>
  </dict>
</dict>
</plist>

Migration: Xcode can automatically convert .strings + .stringsdict to .xcstrings. Right-click the files → "Migrate to String Catalog".

Best Practices

1. Use xcstrings — Migrate from legacy formats
2. One catalog per module — Keep Localizable.xcstrings in each target
3. Mark states — Use needs_review for translations that need verification
4. Extract from code — Let Xcode auto-extract strings using String(localized:)
5. Import by language — Import one language at a time into Azbox

Project Structure

MyApp/
├── MyApp/
│   ├── Localizable.xcstrings    ← Main strings
│   └── InfoPlist.xcstrings      ← App Store metadata
└── MyAppTests/
    └── Localizable.xcstrings    ← Test strings (if needed)

---

Related

• ARB Import — For Flutter projects
• JSON Import — For JavaScript projects
• Apple String Catalogs Documentation