Internationalization (i18n) in Swift: NSLocalizedString and String Catalog

Internationalization (i18n) in Swift: A Complete Guide for iOS and macOS

Internationalization (i18n) is the process of designing an application so that it can be adapted to various languages and regions without engineering changes. In the Apple ecosystem (iOS, macOS, watchOS, tvOS), localization tools are built directly into Swift and Xcode. In this article, we will thoroughly examine how to use NSLocalizedString and the modern String Catalog to create multilingual applications.

Basics: NSLocalizedString

The basic internationalization mechanism in Swift is the NSLocalizedString function. It looks up the string translation in .strings or .xcstrings (String Catalog) files.

let greeting = NSLocalizedString("hello_world", comment: "Greeting on the main screen")print(greeting) // Prints the translation depending on the device language

The comment parameter serves as a hint for the translator. The key "hello_world" must be unique within the entire project.

Creating Localization Files

In Xcode, you can add supported languages via Project Info > Localizations. After that, sub-files for localization will be created for each .strings file or Storyboard.

Example content of Localizable.strings (English):

"hello_world" = "Hello, World!";"welcome_message" = "Welcome to our app %@";

Russian version (Localizable.strings (Russian)):

"hello_world" = "Привет, мир!";"welcome_message" = "Добро пожаловать в наше приложение %@";

String Formatting with Parameters

For strings containing dynamic data, use format specifiers. In Swift, this can be done in two ways:

Method 1: String(format:)

let userName = "Ivan"let points = 150let message = String(format: NSLocalizedString("user_score", comment: "User points"), userName, points)print(message) // "Ivan scored 150 points"

In the localization file:

"user_score" = "%@ scored %d points";

Method 2: Swift String Interpolation (iOS 15+)

let message = "\\(userName) scored \\(points) points"

However, this method is not suitable for localization, as word order can differ between languages. Use only String(format:) or AttributedString with inflection.

Pluralization (Plural Forms)

In Russian, there are complex declension rules: "1 file", "2 files", "5 files". For this, Apple provides stringsdict (XML) or String Catalog with pluralization rules.

stringsdict Example

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"  "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict>    <key>files_count</key>    <dict>        <key>NSStringLocalizedFormatKey</key>        <string>%#@files@</string>        <key>files</key>        <dict>            <key>NSStringFormatSpecTypeKey</key>            <string>NSStringPluralRuleType</string>            <key>NSStringFormatValueTypeKey</key>            <string>d</string>            <key>one</key>            <string>%d file</string>            <key>few</key>            <string>%d files</string>            <key>many</key>            <string>%d files</string>            <key>other</key>            <string>%d files</string>        </dict>