String Catalogs in Xcode: A Beginner's Guide to Modern App Localization

App localization used to be a complex process involving multiple .strings files, manual key management, and constant synchronization headaches. With Xcode 15, Apple introduced String Catalogs – a game-changing feature that simplifies localization and makes managing app translations more intuitive than ever before.

What Are String Catalogs?

String Catalogs are a new way to translate text, handle plurals, and vary the text your app displays on specific devices. Think of them as a centralized hub where all your app's localizable strings live in one organized, easy-to-manage place.

Instead of juggling multiple .strings files for different languages, String Catalogs give you:

• One file to rule them all: All translations in a single .xcstrings file
• Automatic key extraction: Xcode automatically detects localizable strings in your code
• Built-in plural handling: No more separate .stringsdict files
• Visual editing interface: A user-friendly editor built right into Xcode

Why Should You Care About String Catalogs?

Before String Catalogs, iOS localization was tedious. You had to:

• Manually create and maintain separate .strings files for each language
• Keep track of keys across multiple files
• Handle plurals with complex .stringsdict files
• Manually sync new strings between files

String Catalogs eliminate these pain points by providing a modern, streamlined approach to localization that saves time and reduces errors.

Getting Started: Creating Your First String Catalog

Step 1: Setting Up a String Catalog

1. Open your Xcode project
2. Right-click on your project navigator
3. Select New File
4. Choose String Catalog from the Resource section
5. Name it Localizable.xcstrings (this is the default name Xcode looks for)
6. Add it to your project

Step 2: Making Strings Localizable in Code

With String Catalogs, you use the new String(localized:) initializer instead of the traditional NSLocalizedString. Here's how:

Old way (NSLocalizedString):

let message = NSLocalizedString("welcome_message", comment: "Welcome message for users")

New way (String Catalogs):

let message = String(localized: "Welcome to our app!")

The beauty of String Catalogs is that you can use the actual text as the key, making your code more readable and self-documenting.

Step 3: Adding Comments for Translators

Comments help translators understand context. Add them like this:

let message = String(localized: "Welcome to our app!", 
                    comment: "Greeting message shown on the home screen")

Step 4: Automatic Key Extraction

Here's where the magic happens. When you build your project, Xcode automatically:

• Scans your code for String(localized:) calls
• Extracts the strings and adds them to your String Catalog
• Creates entries that you can then translate

Working with the String Catalog Editor

Once Xcode extracts your strings, you'll see them in the String Catalog editor:

1. Key Column: Shows your localizable string keys
2. Development Language: Your base language (usually English)
3. Translation Columns: One for each language you're supporting
4. State Indicators: Shows translation status (new, translated, needs review)

To add a new language:

1. Select your String Catalog file
2. Click the + button in the editor
3. Choose your target language
4. Start translating!

Handling Plurals Made Simple

One of the most powerful features of String Catalogs is built-in plural handling. Instead of creating complex .stringsdict files, you can handle plurals directly in the catalog.

In your code:

let itemCount = 5
let message = String(localized: "^[\(itemCount) item](inflect: true)")

In the String Catalog: The editor automatically provides fields for different plural forms based on the target language's rules:

• Zero: "No items"
• One: "1 item"
• Other: "%d items"

Device-Specific Variations

String Catalogs also support device-specific text variations. You can provide different text for:

• iPhone vs iPad
• Different screen sizes
• Accessibility settings

This ensures your app's text looks perfect on every device.

Migrating Existing Projects

If you have an existing project with .strings files, don't worry! Xcode makes migration straightforward:

1. Select your existing .strings files in the project navigator
2. Right-click and choose Convert to String Catalog
3. Xcode will create a new .xcstrings file with all your existing translations
4. Gradually update your code to use String(localized:) instead of NSLocalizedString

Pro tip: You can migrate gradually. String Catalogs work alongside traditional .strings files, so you can migrate at your own pace.

Best Practices for String Catalogs

1. Use Descriptive Keys

// Good
String(localized: "Delete this item?", comment: "Confirmation dialog for item deletion")

// Avoid
String(localized: "delete_confirmation")

2. Provide Context with Comments

Always include comments that help translators understand:

• Where the text appears
• What the text does
• Any constraints (character limits, etc.)

3. Group Related Strings

Organize your String Catalog by using consistent prefixes or grouping:

String(localized: "Settings: Account", comment: "Account section header")
String(localized: "Settings: Privacy", comment: "Privacy section header")

4. Test Your Localizations

Use Xcode's localization debugging features:

• Enable "Show non-localized strings" to find missing translations
• Test on devices set to different languages
• Use pseudolocalization to test text expansion

Common Pitfalls and How to Avoid Them

1. Forgetting to Use the New Initializer

Make sure you're using String(localized:) instead of NSLocalizedString for new strings. Only the new initializer works with automatic extraction.

2. Not Providing Comments

Comments are crucial for translators. A string like "OK" could mean "Okay/Alright" or "Correct" depending on context.

3. Hardcoding Strings in Interface Builder

Remember to localize strings in your storyboards and XIB files too. Use the localization features in Interface Builder.

4. Ignoring Plural Rules

Different languages have different plural rules. Let String Catalogs handle this automatically rather than trying to implement your own logic.

Exporting and Working with Translators

When you're ready to work with professional translators, you can export your localizable files in XLIFF format:

1. Select your project in the navigator
2. Choose Product > Export Localizations
3. Select your target languages
4. Xcode exports .xliff files that translators can work with
5. Import completed translations with Product > Import Localizations

Advanced Features

String Interpolation

String Catalogs support string interpolation with automatic placeholder handling:

let name = "John"
let greeting = String(localized: "Hello, \(name)!")

Custom String Catalogs

You can create multiple String Catalogs for different modules or features:

let message = String(localized: "Welcome!", bundle: .module, comment: "Module welcome message")

Troubleshooting Common Issues

Strings Not Appearing in Catalog

• Make sure you're using String(localized:)
• Clean and rebuild your project
• Check that the String Catalog is added to your target

Translations Not Loading

• Verify your String Catalog is included in your app bundle
• Check the catalog's target membership
• Ensure you're using the correct bundle parameter

Build Errors After Migration

• Remove old .strings files if you've fully migrated
• Clean derived data and rebuild
• Check for duplicate string keys

What's Next?

String Catalogs represent the future of iOS localization. As demonstrated in Apple's WWDC 2023 session, they make it easy to localize your app by managing all of your strings in one place. They eliminate the complexity of traditional localization workflows while providing more powerful features for handling plurals and device variations.

Whether you're starting a new project or maintaining an existing app, String Catalogs will save you time and make your localization process more reliable and maintainable.

Key Takeaways

• String Catalogs centralize all your app's localizable text in one file
• Use String(localized:) for automatic string extraction
• Built-in plural handling eliminates the need for .stringsdict files
• You can migrate existing projects gradually
• Always provide context with comments for translators
• Test your localizations thoroughly before release

Start using String Catalogs in your next project, and experience how much simpler app localization can be. Your future self (and your translators) will thank you!

References

All information in this article is based on official Apple documentation and resources:

Official Apple Documentation

• String Catalogs Overview: Localizing and varying text with a string catalog - Apple Developer Documentation
• Localization Guide: Localization - Apple Developer Documentation
• String Localization: String(localized:table:bundle:locale:comment:) - Swift Documentation

WWDC Sessions

• WWDC 2023: "Discover String Catalogs" - Session covering the introduction and implementation of String Catalogs in Xcode 15
• WWDC 2023: "Build apps that scale with Swift and SwiftUI" - Additional context on modern Swift localization practices

Apple Developer Resources

• Xcode 15 Release Notes: Information about String Catalog features and compatibility
• Localization Best Practices: Apple's official guidelines for app internationalization
• Swift Evolution Proposals: Background on the String localization APIs

Additional Resources

• Apple Human Interface Guidelines: Internationalization and localization guidelines for iOS apps
• App Store Connect Help: Guidelines for submitting localized apps

Note: All code examples and implementation details are based on official Apple documentation and best practices as of Xcode 15 and iOS 17.