iOS Internationalization and Localization Guide + Demo App

Part 2: Setting Up Your Xcode Project

We’ll be working with Bookshelf, a simple demo app that allows users to track how many books they’ve read. It’s built with SwiftUI and minimal by design.

By the end of this guide, BookShelf will run in English, Spanish, and Arabic, handle plural strings correctly across all three languages, and mirror its layout automatically for Arabic readers. 

Open BookShelf in Xcode and select the project file in the Navigator. Under the Info tab, scroll to the Localizations section. English is already listed as the base language. Click the + button to add your first language. We’ll add Spanish and Arabic for this demo.

Next, add a String Catalog. 

1. Right-click on your project and select New File from Template.
2. Search for String Catalog and add it. The default name will be Localizable.xcstrings. No need to change it.
3. Build the project once with Cmd+B. Xcode will scan your code, find every localizable string, and populate the catalog automatically. 

Selecting New File from Template

Adding String Catalog

After building the project, open Localizable.xcstrings and you’ll see Xcode has already extracted every string literal from your SwiftUI views and added them to the catalog with their English values filled in. For most strings, that’s all you need to do.

There are a couple of patterns where Xcode can’t do this automatically, and both fail silently, with the app just displaying the untranslated string with no warning.

When you pass a variable to a Text view instead of a string literal, SwiftUI treats it as a plain string and skips the catalog lookup entirely.

// NOT localized
let title = "welcome_title"
Text(title)

// Localized correctly
Text(LocalizedStringKey(title))

// NOT localized
let title = "welcome_title"
Text(title)

// Localized correctly
Text(LocalizedStringKey(title))

For strings you need to localize in a view model, helper function, or anywhere outside a SwiftUI view, use String(localized:) rather than a plain string.

let errorMessage = String(localized: "error_generic")

let errorMessage = String(localized: "error_generic")

Strings sometimes need different versions depending on context. This includes plural forms that change with a number, or text that differs by device. You can manage both directly in the String Catalog.

Pluralization

BookShelf, our demo app, shows a count of books on the user’s shelf. In English that’s simple: “1 book” vs “3 books”. But plural rules vary across languages, and getting this wrong produces unnatural text in other locales.

Start with the string in your SwiftUI view:

Text("\(bookCount) books on your shelf")

Open the String Catalog, right-click the key, and choose Vary by Plural. Xcode generates the plural categories automatically and pre-fills them with the source string. 

Selecting Vary by Plural

Automatically generated plurals

For English, you’ll see One and Other. Just correct the One field to the singular form: “%lld book on your shelf”. The Other form is already right as-is.

Xcode marks both as Needs Review until you confirm them. Once you’ve corrected the One form, you can mark them as reviewed.

You’ll also see Arabic and Spanish listed in the sidebar at 0%. You don’t need to do anything for those languages now. Later, when you export to PTC for translation, the plural structure travels with the file. For Arabic, PTC will generate translations for all six plural categories (zero, one, two, few, many, and other) because Arabic grammar requires all six. For Spanish, it’s two, same as English.

Device Variations

Some text should differ by device, such as “Tap to continue” on iPhone vs “Click to continue” on Mac. To set this up, right-click the key in the catalog and choose Vary by Device. Add the devices you want to customize and enter the appropriate string for each. At runtime, iOS serves whichever version matches the current device.

Device variations are less common than plural variations, but useful for apps that run on both iOS and macOS.