Localization of iOS App

An app that supports localization will likely need to replace the following to adjust to different languages:

  • Text in the user interface such as buttons and labels
  • Images
  • Text displayed by code
  • The name of the app displayed on the Home screen

Localization works by creating multiple files to store the text you want to display in other languages. To create localization files, you need to define which languages you want your Xcode project to support. For each language you want your app to support, you’ll need to define one localization setting.

To see how to add localization to a project, follow these steps:

  1. Click the project name at the top of the Navigator pane. Xcode displays information about the project in the middle pane.
  2. Click the project name under the Project category at the top.
  3. Click Info at the top of the middle Xcode pane. Xcode displays an Info pane.
  4. Click the + icon under the Localizations category. A popup menu appears of different languages.
  5. Choose a language you want your app to support. For this example, choose Ukraine. A window appears, displaying all the files to localize.
  6. Make sure all options are selected and click the Finish button. Notice that Xcode now displays a gray disclosure triangle to the left of the Main.storyboard file in the Navigator pane.
  7. Click this gray disclosure triangle to the left of the Main.storyboard file. Notice that Xcode has now created two additional files: Main.storyboard (Base) that represents your native language and Main.strings (Ukraine) (or whatever language you chose)

The Main.storyboard (Base) file contains the storyboard of your project where you can design the user interface. The Main.strings file contains text to display on the user interface. Xcode identifies the text to appear in the user interface by the Object ID, which appears on the Identity Inspector pane.

To view the Object ID of a user interface object, follow these steps:

  1. Click the Main.storyboard file in the Navigator pane.
  2. Click the Identity Inspector icon in the upper right corner of the Xcode window. The Object ID appears.

Storing text

The most common way to store localized text in an app looks like

var greeting = NSLocalizedString("Hello", comment: "Formal greeting")

The comment portion of the NSLocalizedString is optional, but is meant to help a translator understand the context of the text. This can help a translator more accurately translate your text based on the comment you provide.

Once you’ve identified text in your code as NSLocalizedString, the next step is to edit the Main.strings file that shows the user interface (identified by Object ID) and its equivalent word or term in another language.

In our example, let’s assume that we want to display a greeting in a label. That means we’ll need both our native language text and the foreign language text to appear in a label, identified by its Object ID.

When we define a localization file (such as Ukraine), Xcode automatically creates a Main.strings file that identifies user interface objects by their Object ID such as

/* Class = "UILabel"; text = "Hello"; ObjectID = "X1f-Wi-Yee"; */
"X1f-Wi-Yee.text" = "Привiт";

What we need to do is customize this Main.strings file to display the foreign language equivalent. To do this follow these steps:

Edit the viewDidLoad method as follows:

override func viewDidLoad() { super.viewDidLoad()
    greetingLabel.text = NSLocalizedString("Hello", comment: "Formal greeting")
}
  1. Click the Main.storyboard file in the Navigator pane.
  2. Click the Assistant Editor icon in the upper right corner of the Xcode window. Xcode displays the Main.storyboard and ViewController. swift file side by side.
  3. Click the double circle icon at the top in the assistant editor (the window on the right). A popup menu appears.
  4. Choose Preview > Main.storyboard (Preview). Xcode displays a preview of the Main.storyboard file in the assistant editor (the right pane). In the bottom right corner of the assistant editor, a Language button displays your native language such as English.
  5. Click this Language button that displays your current language (such as English). A popup menu appears.
  6. Choose Ukraine. Notice that Xcode now displays the Ukraine translated text in the user interface.

Creating a Localized String File

At this point if you run the app, it will always display the text "Hello" in the label that appear on the user interface regardless of the iOS device’s language preference. That’s because even though we defined what Ukraine text to appear on the user interface through the Main.strings (Ukraine) file, we still need to define what strings to appear when the app actually runs. The Main.strings (Ukraine) file just lets us preview our user interface with different languages, but does not define which foreign language words to use while the app runs.

To do this, we need to define each text to replace everywhere we defined text as NSLocalizedString. That means we need to follow these steps:

  • Replace text everywhere in our NSLocalizedString code to define placeholder text to appear.
  • Create a localized string file that defines which native language terms to replace in the placeholder text.
  • Create one or more additional localized string files to define which foreign language terms to replace in the placeholder text.

To see how to create localized string files for each foreign language you want to support, follow these steps:

  1. Make sure you have created at least one localization file for an additional foreign language to support such as Ukraine.
  2. Choose File > New > File. A template dialog appears.
  3. Scroll down and click the Strings File icon under the Resource category under iOS.
  4. Click the Next button. A dialog appears, asking where you want to save the file.
  5. Change the file name to Localizable.strings.
  6. Click the Create button. Xcode adds the Localizable.strings file to the Navigator pane and also displays a File Inspector pane
  7. Click the Localize button in the File Inspector pane. A dialog appears asking if you want to localize this file.
  8. Click the Localize button. Xcode displays a Localization category in the File Inspector pane. Notice that your native language check box appears selected (such as English), while the other foreign language check box is clear.
  9. Select the Ukraine check box. Xcode displays a gray disclosure triangle to the left of Localizable.strings in the Navigator pane.
  10. Click the gray disclosure triangle that appears to the left of Localizable.strings. Notice that Xcode has now created two Localizable.strings, one for each language you want to support.

At this point, both .strings files are empty. What we need to do is go through our code, put placeholder text in all NSLocalizedStrings, and define what actual text we want to appear for each placeholder text. The names we give our placeholder text can be any arbitrary text as long as it’s distinct and unique. For our example, we’ll use the following placeholder text:

greeting_text

To see how to display text in foreign languages in our app, follow these steps:

  1. Make sure you have created at least one localization file for an additional foreign language to support such as Ukraine.
  2. Make sure you have created a separate .strings file for each language you want your app to support (such as two .strings files for English and Ukraine).
  3. Click the ViewController.swift file in the Navigator pane.
  4. Edit the viewDidLoad method as follows:
greetingLabel.text = NSLocalizedString("greeting_text", comment: "Formal greeting")

Click the Localizable.strings (English) file in the Navigator pane. Add the following inside the Localizable.strings (English) file:

"greeting_text" = "Hello";

Click the Localizable.strings (Ukraine) file in the Navigator pane. Add the following inside the Localizable.strings (Ukraine) file:

"greeting_text" = "Привiт";

Now that we’ve defined placeholder text along with English and Ukraine words to appear when the app runs, it’s time to test the app as if the iOS Simulator were running in a different language.

Localizing Images

To localize text, we needed to insert placeholder text in our code. Then we had to create two separate Localizable.strings files where each .strings file contained both the placeholder text we used and its actual text we want the app to use for different languages such as

"greeting_text" = "Hello";

Localizing images is no different except you use placeholder text to specify a file name to display. Then you need a different image for each language such as an image for English and a different image for Ukraine such as

let imageFile = NSLocalizedString("flag_file", comment: "National flag") 
myImageView.image = UIImage(named: imageFile)

In each language’s Localizable.strings file, you need to specify the exact file name such as

"flag_file" = "usaFlag";

Now you just need an image named usaFlag in your project. For the purposes of this project, we’ll assume the American flag image is called usaFlag.png and the Ukraine flag is called ukFlag.png.

Drag both flag images into your project’s Navigator pane. When a dialog appears, click Finish button. Xcode should now display the two flag images in the Navigator pane.

Customizing the App Name

One final step to localization is customizing the app name. To do this, you need to create a separate InfoPlist.strings file for each language you want to support. Then in each InfoPlist.strings file, you define the CFBundleDisplayName value such as

"CFBundleDisplayName" = "App Name";

Whatever name you define here is what appears underneath the app’s icon when it appears on the Home screen. To see how to localize the name for your app, follow these steps:

  1. Choose File > New > File. A template dialog appears.
  2. Scroll down and click the Strings File icon under the Resource category under iOS.
  3. Click the Next button. A dialog appears, asking where you want to save the file.
  4. Change the file name to InfoPlist.strings.
  5. Click the Create button. Xcode adds the InfoPlist.strings file to the Navigator pane and also displays a File Inspector pane.
  6. Click the Localize button in the File Inspector pane. A dialog appears asking if you want to localize this file.
  7. Click the Localize button. Xcode displays a Localization category in the File Inspector pane. Notice that your native language check box appears selected (such as English), while the other foreign language check box is clear.
  8. Select the Ukraine check box. Xcode displays a gray disclosure triangle to the left of InfoPlist.strings in the Navigator pane.
  9. Click the gray disclosure triangle that appears to the left of InfoPlist.strings. Notice that Xcode has now created two InfoPlist. strings, one for each language you want to support.
  10. Click the InfoPlist.strings (English) file in the Navigator pane.
  11. Add the following to the InfoPlist.strings (English) file:
"CFBundleName" = "$(PRODUCT_NAME)";
"CFBundleDisplayName" = "USA App";
  1. Click the InfoPlist.strings (Ukraine) file in the Navigator pane.
  2. Add the following to the InfoPlist.strings (Ukraine) file:
"CFBundleDisplayName" = "Ukraine App";
  1. Click the Run button. The Simulator screen appears.
  2. Choose Hardware > Home to display the Home screen on the Simulator.
  3. Click the Settings icon.
  4. Click General.
  5. Click Language & Region.
  6. Click iPhone Language. A list of languages appears.
  7. Choose Ukraine and then click Done. Notice that now your app displays "Ukraine App" on the Home screen.

Formatting Numbers and Dates

Every region tends to display numbers and dates in different ways. To make your app format data such as numbers and dates based on the user’s language and region, use Apple’s various Formatters such as NumberFormatter or DateFormatter. Apple’s various formatters can automatically adjust the appearance of data based on the iOS device’s language and region. Your app just needs to calculate the data to appear on the user interface.

The basic step to using a formatter involves choosing which formatter to use such as

let formatter = DateFormatter()
let formatter2 = NumberFormatter()

Then define one or more settings for how to format the information such as

formatter.dateStyle = .full
formatter2.numberStyle = .currency

Finally, use the formatter to convert the data such as

let myDate = formatter.string(from: Date())
let myMoney = formatter2.string(from: 123456)

dateLabel.text = NSLocalizedString("\(myDate)", comment: "Date format")
numberLabel.text = NSLocalizedString("\(myMoney!)", comment: "Number format")

To see the differences in how the formatters work, we need to run our app as if we’re in a different region of the world. So not only can we set the language for the Simulator to use, but we can also define the region for the Simulator to mimic.

  1. Click the Scheme button (it displays your project’s name) that appears in the upper left corner of the Xcode window. A popup menu appears.
  2. Choose Edit Scheme. A window appears. Click Options.
  3. Click Run in the left pane.
  4. Click the Application Language popup menu and choose the language you want the Simulator to mimic such as Ukraine.
  5. Click the Application Region popup menu and choose a different region such as Ukraine.
  6. Click the Close button.
  7. Click the Run button.