How to use String Catalogs for localization in Swift

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.

Capture HTTP(s) traffic with Proxyman

Proxyman - Your ultimate man-in-the-middle proxy to effortlessly capture, inspect, and manipulate HTTP(s) traffic on macOS, Windows, iOS, and Android devices.

Get started for free

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:

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:

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.

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.

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 (coming soon) to learn more.

Capture HTTP(s) traffic with Proxyman

Proxyman - Your ultimate man-in-the-middle proxy to effortlessly capture, inspect, and manipulate HTTP(s) traffic on macOS, Windows, iOS, and Android devices.

Get started for free