Migrating from Localizable.strings to String Catalogs

Xcode 15 introduced String Catalogs (.xcstrings) as the modern replacement for the venerable .strings format. If you've got years of translations in the old format, migration is straightforward—and the benefits are worth it.

Why Migrate?#

The old .strings format is flat key-value pairs. It works, but it's limited:

• No plural support. You need separate .stringsdict files for plurals.
• No device variations. Can't have different strings for iPhone vs. Mac.
• No state tracking. You can't tell which strings are translated, stale, or need review.
• No visual editor. It's just a text file.

String Catalogs fix all of this. One file, structured JSON, with built-in support for everything localization needs.

Before You Start#

Commit your current state. Make sure your git working directory is clean. You'll want to be able to diff the migration.

git add .
git commit -m "Pre-migration snapshot"

Back up your .strings files. The migration is reversible, but peace of mind is free.

Step 1: Xcode's Migration Wizard#

Xcode can migrate automatically. In your project:

1. Select your .strings file in the navigator
2. Go to Editor → Migrate to String Catalog...
3. Follow the prompts

Xcode creates a new .xcstrings file and imports all your existing translations. The old .strings file stays in place until you delete it.

For .stringsdict files (plurals), Xcode merges them into the String Catalog automatically. Your plural rules are preserved.

Step 2: Verify the Conversion#

After migration, check that everything came through:

# See what changed
git diff

# Check the new file exists
ls *.xcstrings

Open the new String Catalog in Xcode. Browse through your strings. Make sure:

• All keys are present
• Existing translations are intact
• Plural variations are correctly structured
• Comments were preserved

Step 3: Edge Cases#

InfoPlist.strings#

InfoPlist.strings handles special keys like CFBundleDisplayName. Xcode 15+ supports migrating this too, but verify that your app name and permission descriptions came through correctly.

Manual String Files#

If you have custom .strings files loaded manually (not through Xcode's standard localization), you may need to update your loading code:

// Old way
Bundle.main.localizedString(forKey: key, value: nil, table: "Custom")

// Still works—String Catalogs are backwards compatible

String Catalogs are JSON files, but they support the same NSLocalizedString and SwiftUI Text() APIs. Your code doesn't need to change.

Stringsdict Plurals#

If you have complex .stringsdict files with nested substitutions, double-check that the migration preserved the logic. Open both files side-by-side and compare.

Step 4: Update Build Settings#

If you had custom build settings for .strings file generation, review them. Most projects don't need changes, but if you're doing anything unusual with localization at build time, test it.

Step 5: Clean Up#

Once you've verified everything works:

# Remove old files
git rm Localizable.strings
git rm Localizable.stringsdict

# Commit the migration
git commit -m "Migrate to String Catalogs"

Common Gotchas#

Missing translations after migration. Sometimes Xcode doesn't pick up all .lproj folders. Manually check each language folder and verify strings were imported.

Encoding issues. Old .strings files were sometimes UTF-16. String Catalogs are UTF-8. If you see garbled characters, re-export from your translation management system.

stringsdict not merged. If your plurals didn't come through, try migrating the .stringsdict file separately, then manually merging.

What's Next#

With your project on String Catalogs, you can:

• Use XCStrings Translator for AI-powered translation
• Take advantage of plural variations in any language
• Set up device-specific strings for iPhone, iPad, and Mac
• Track translation state (new, translated, needs review, stale)

The modern format is better in every way. The migration is usually painless. And once you're on String Catalogs, tools like XCStrings Translator can help you translate faster than ever.

Related#

• Getting Started — Set up XCStrings Translator with your new String Catalog
• Understanding Plural Rules — Take advantage of proper plural support
• XCStrings Format Overview — Technical details on the file format