Logo for tanaschita.com

How to use String Catalogs for localization in Swift

Learn how to work String Catalogs introduced at WWDC23.

26 Jun 2023 · 4 min read

At WWDC23, Apple introduced String Catalogs which is a new way to add localization to iOS projects.

Let's directly jump in and look at how String Catalogs work.

Sponsorship logo
Preparing for a technical iOS job interview - updated for iOS 17
Check out my book on preparing for a technical iOS job interview with over 200 questions & answers. Test your knowledge on iOS topics such as Swift, SwiftUI, Combine, HTTP Networking, Authentication, SwiftData & Core Data, Concurrency with async/await, Security, Automated Testing, Machine Learning and more.
LEARN MORE

What is a String Catalog

A String Catalog is a file with the extension .xcstrings, by default named Localizable.xcstrings.

Contrary to Localizable.string and Localizable.stringdict files, a String Catalog manages all translations in one single file:

String Catalog example in Xcode.
A String Catalog manages all translations in one single file.

Internally, a String Catalog is represented by a JSON structure:

{
"sourceLanguage" : "en",
"strings" : {
"loginButton.title" : {
"localizations" : {
"de" : {
"stringUnit" : {
"state" : "translated",
"value" : "Login"
}
},
"en" : {
"stringUnit" : {
"state" : "translated",
"value" : "Login"
}
}
}
}
},
"version" : "1.0"
}

Automatic detection of localizable strings

Xcode automatically detects and adds localizable strings to the String Catalog every time we build the project.

For example, when using SwiftUI's text view with Text("loginButton.title"), Xcode automatically creates a new entry for us:

Xcode detects localized strings automatically.
Xcode detects localized strings automatically.

After Xcode creates an entry, we can add the corresponding translations using Xcode's build-in editor.

When passing around localized strings, we can use the LocalizedStringResource type to enable autodetection for those.

Manual management of localized strings

In case we dont's want Xcode to manage entries automatically, we can configure them to be managed manually.

String Catalog Stale state.
Manage String Catalog entries manually

Manually managed strings are never updated or removed by Xcode.

Different String Catalog states

Xcode automatically deletes entries when we remove them from our code base, but only if we didnt't provide any translations yet. Otherweise, these entries are marked as STALE.

String Catalog Stale state.
Manage String Catalog stale state

When Xcodes detects missing strings and marks them as stale, we can either delete the entry or use the inspector to tell Xcode that we'll manage it manually.

There are other localization states an entry in a String Catalog can have, for example NEW which indicates that a string hasn't been translated yet.

A green checkmark indicates that the entry is translated.

String pluralization

Another feature coming with String Catalogs is String pluralization. Check out this article on how to use String Catalogs for pluralization to learn more.

Sponsorship logo
Preparing for a technical iOS job interview - updated for iOS 17
Check out my book on preparing for a technical iOS job interview with over 200 questions & answers. Test your knowledge on iOS topics such as Swift, SwiftUI, Combine, HTTP Networking, Authentication, SwiftData & Core Data, Concurrency with async/await, Security, Automated Testing, Machine Learning and more.
LEARN MORE

Newsletter

Image of a reading marmot
Subscribe

Like to support my work?

Say hi

Related tags

Articles with related topics

localization

swift

ios

How to use String Catalogs for pluralization in Swift

Learn about pluralization and variables in String Catalogs.

10 Jul 2023 · 3 min read

Latest articles and tips

© 2024 tanaschita.com

Privacy policy

Impressum