There are three main things you need to consider when localizing iOS apps:
- Use translated text in your Swift code.
- Translate text used in interface layout (XIB or Storyboard files)
- If necessary create a separate interface layout for a language.
Maintaining separate interface layout files for different languages can be difficult. You do that only when the UI is significantly different for different languages. In this tutorial we will discuss the first two techniques only.
Using translated text in code
Add localized resource
You may have code like this:
priceLabel.text = "Price"
Such text needs to be externalized from code so that they can be translated. At runtime iOS will will load the text for the language appropriate for the device.
First create a Strings resource file. From the menu select File > New > File. Then choose Resource > Strings file.
Enter Localizable.strings as the file name. The file name must be Localizable.strings. Click Create.
In Xcode you must explicitly declare each Strings, XIB and Storyboard file as localized.
Select the newly created Localizable.strings file.
In the file inspector click the Localize button.
From the language list drop down select Base. “Base” the default language. Text will be retrieved from this language unless iOS finds a translation for the text in a specific language. If you are an English speaking developer you can enter all English text in the Base language. There is no need to create a separate resource file for English.
Click Localize. The file will now be moved under the Base.lproj folder.
Before we add other languages, let’s see how to add text to this file and use it from your code. The strings file has the following format.
Open the Localizable.strings file and add this line:
"first_name"="Your first name:";
Note: Don’t forget the ;. It is mandatory.
Now you can load the text from your code and print it out like this:
let str = NSLocalizedString("first_name", comment: "First name") print(str)
Often you need to show a formatted string with dynamic values, such as “Name: Daffy Duck Age: 24”. There is no direct way to supply value parameters to NSLocalizedString. Instead, you need to store the format specifier string in Localizable.strings and then format it using a String constructor. For example, the localized resource will have:
"name_and_age"="Name: %2$@ Age: %1$d";
Then create a formatted string in your code like this:
let s = String(format: NSLocalizedString("name_and_age", comment: ""), 24, "Daffy Duck")
Always use positional parameters using the n$ syntax. Because different languages may insert the values in different order.
Note: NSLocalizedString is a special macro. Later we will learn to export XLIFF files for translation. During the export Xcode inspects all your source code and looks for NSLocalizedString calls. You must use string literals as keys as shown above. If you do, Xcode will include the text in the exported XLIFF file.
Add other languages to project
Go to your project settings. Select the Info tab.
Under Localizations click the + icon. Then select a language like Spanish (es).
From the list of localized files choose the strings resource file we have just added. Do not select any existing Storyboard or XIB files unless you wish keep separate copies of them for different languages.
Click Finish. This will create a copy of Localizable.strings in es.lproj folder. You can now enter translated text in es.lproj/Localizable.strings and iOS will load those values when the device is set to use Spanish language.
Use translated text in XIB or Storyboard
For most screens you can define the layout for the “Base” language and simply provide translated text. iOS lets you define different layouts for different languages but we won’t get into that here.
First create a XIB or Storyboard file using the normal process. For example when you create a new UIViewController or table cell you can choose to have a XIB file created for you.
While the layout file is open in the editor from the file inspector click the Localize button. We have already seen how to do that for the strings resource. Localize the file for the “Base” language only. Doing so will actually move the file under Base.lproj folder. If you are localizing an old layout file, Git should preserve its history.
You can now add labels and other views to the layout as usual. All the text that your hard code in the layout are for the “Base” or default language. We will now translate these texts for the other languages. Since we have only a single copy of the layout file we can not directly provide the translated text from the interface builder editor. We must export the English text, translate them to a language and import it back.
Export localized text
We will now export all localized text in an XML file. This can then be edited by a translator. The file will contain text from:
- Strings resource file
- XIB or Storyboard files that have been localized
In Xcode select your project to view the settings. From the menu select Editor > Export For Localization. Choose Existing Translations.
Select a folder and click Save. Xcode will create a file for each language in your project (except for Base). For example, if you have Chinese and Spanish then cn.xliff and es.xliff files will be created within the export folder.
Exported files are in XML format with an XLIFF extension.
The XLIFF file should include:
- Text from all localized XIB files.
- All text from your localized string file (Localizable.strings). However, there is a catch. Only the keys used as string literal in your NSLocalizedString calls are included.
The exported files can be edited using an XLIFF tool such as this. You can also edit the XML file in a plain text editor. Open the file in an editor and you will see the text that needs to be translated. Text in “Base” language is within the <source> element.
Provide the translated text within a <target> element. In the example below, we edit es.xliff and provide the Spanish translation.
Save the file.
Import translated text
Once you get the XLIFF file for a language translated by the translator you can import it into Xcode. Select the project to view its settings. From the menu select Editor > Import Localizations. Choose the XLIFF file and import it.
Previewing translated UI
To test for a language you can change the language settings of your device or simulator. But a faster way will be to do a preview in Xcode.
Open the XIB or Storyboard in interface builder. Then open the companion editor.
From the menu of the companion editor choose the preview option.
By default you will see the “Base” language. From the bottom right corner you can switch the language as shown below.
Switching to Spanish will change preview like this.