iOS Localization Guide for Multilingual iPhone and iPad Apps

This guide will show you how to convert a single-language iOS application, built with Xcode, into a multilingual application.

Contents:

1. Making Resources Localizable in Xcode
2. Localizing Interface Builder files
3. Collecting embedded texts into resource files
4. Translating the resource files
5. Importing the translation to the iOS application
6. Testing the translation in an iOS device

 

Introduction

The process of localizing an iOS application involves these steps:

1. Getting your resource files ready for localization.
2. Collecting all the texts used in the application in resource files.
3. Translating the resource files.
4. Integrating the resource files back in the application.

Since iOS apps are multilingual by design, once your application is available in multiple languages, the device already knows what to do. It will display the GUI texts in the right language, according to the devices’s language setting.

All iOS applications are built using Unicode texts, encoded as UTF-16. The iPhone and iPad simulators support this format and will allow you to preview your translated application.

1. Making Resources Localizable in Xcode

Xcode needs to know that your project includes multilingual resource files.

The easiest way to make a file localizable with Xcode is to simply remove the file from the project and, in Finder, move it into the localized directory. Make sure you click on “Delete References” and not “Also Move to Trash” when removing the file from your project, so that the file itself isn’t deleted but only the reference to it in the project is removed.

If your source resource files are in English, then create a new folder called en.lproj in your project’s folder. If your source resource files are in a different language, replace the en with the two-letter country code.

Move the resource file into the new localization directory, and then drag the resource into the Xcode project. Xcode will now recognize the resource as localized in that language. Repeat for all your other resource files that you need to localize.

2. Localizing your Interface Builder files

Extracting the strings

To extract the strings from your Interface Builder resource files, you need to run a tool like ibtool, included with the standard developer kit install.

To extract the files, open Terminal in the project directory and run the command:
ibtool --generate-strings-file Example.strings en.lpoj/Example.xib
This will create the file Example.strings. Open it and you’ll see a bunch of object-string value pairings.

Go through this document carefully and check its contents. You can remove unnecessary strings, which don’t require translation.

Handling duplicate strings

The resource file may contain duplicate strings, such as some of the titles for buttons in different states.

Some duplicate strings need to be translated just once but other duplicate strings have different translations. The same button title, in different states, should clearly have the same translation. However, strings can once be a noun and in other places be a verb.

You can remove redundant duplicate strings (which should have the same translation) from the resource file or leave them there and instruct the translator to handle as duplicate strings.

ICanLocalize’s iOS translation system can automatically remove duplicate strings from resource files, simplifying this task.

3. Collecting the embedded texts into resource files

Normally, iOS applications contain two kinds of texts. There are the application’s interface (managed by the Interface Builder) and embedded strings that appear inline in the code itself.

The strings in the interface are already arranged in a resource file and we need to make sure that the code itself only uses strings that are read from a resource file too.

An inline string would look like this:

@"Hello World!"

We need to edit the source files and change all inline strings to look like this:

NSLocalizedString(@"Hello World", @"hello message")

Now, “Hello World” is actually a token. The NSLocalizedString function will produce the string that will be output. It will return the localized string according to the application’s language. NSLocalizedString will read the Localizable.strings file from the localization directory.

Go through all your code and determine which strings are user-facing and should be localized. Don’t localize strings the user will never see, such as keys in an NSDictionary (unless, of course, you ever display those keys).

Adding comments

Did you notice that “hello message” (the second argument)?

This is a comment, which will go into the resource file and be also visible to the translator. It’s very important to add comments in places where the text is not self explanatory. This way, the translator who’s translating your application will know what the text is used for and how to translate it correctly.

Creating a Localizable.strings file

genstrings will collect all the strings that need to be translated from the source files and create the Localizable.strings file. To run it, open Terminal, go to the project directory and run:

genstrings -o en.lproj *.m

This will pull all the keys from the NSLocalizedString calls, and compile them into one Localizable.strings file in the en.lproj localization directory. If your class files are in a different directory, make sure you include them at the end of this command (e.g. Classes/*.m).

4. Translating the resource files

Now, you should have two resource files. The Interface Builder resource file (created by ibtool) and the embedded strings resource file (created by genstrings).

You can send both files for translation by ICanLocalize.

We have a special tool for localizing iOS resource files, which allows translating iOS applications without spending any time on technical tasks. The tool will read your resource files, extract the texts that need to be translated and produce translated resource files.

You can upload the resource files in UTF-16 or UTF-8 encoding. The tool will extract pairs of labels and strings (and comments if there are any). Professional translators, who have ample experience in localizing iOS applications, will translate just the strings. You will communicate directly with your translators to make sure that translation is not just accurate, but also adapted to the culture and customs of other countries.

You will need to create an account (free). Then, create an iOS translation project, upload your resource files, choose which languages to translate to and pay for the translation. Once completed, you’ll be able to download the localized resource files and import back to your application.

And, even long after the translation has been completed, should you ever need to update or fix it, our translators will be happy to help.

5. Importing the translation to the iOS application

Building the localized xib

Once you’ve gotten your translated strings file back, fire up Terminal again and use it to build a localized copy of that xib.

First, make sure you have created a directory for that localization that you just received, for example “fr.lproj”. Move the translated strings file into that localization directory.

Assuming your source language was English, go to your project directory, open the Terminal and run:

ibtool --strings-file fr.lproj/Example.strings en.lproj/Example.xib –write fr.lproj/Example.xib

This will copy the English-localized Interface Builder file into the other localization directory, and replace the values of all objects with those in the translated strings file.

You now have a localized .xib, but the file isn’t ready to go yet.

Adding the Localized File to Xcode

Drag the freshly localized .xib file into your project in Xcode. Make sure you don’t drag the file into the existing localization. The localized .xib file should go into the grouping that’s holding the other localizations of this file.

Correct place to drop the .xib file	Wrong place to drop the .xib file

Review the Translated Interface Builder File

Open up the translated file in Interface Builder, and go through everything. Often the lengths of different strings will have changed significantly. Translation from English to German and French is often 50% longer than the original text. You may need to adjust the layout slightly to make sure that everything is visible.

If you manually removed any duplicates, now is the time to put them back by duplicating the translated strings. For example, if two buttons shared the same title, and you removed one of the buttons from the .strings file you generated earlier, you will now need to copy the title from the button that did get translated.

You only need to do this if you edited the .strings file before submitting to translation. ICanLocalize‘s system already removes duplicates from the translation and re-inserts them to the translated resource file.

Your iOS application should now run multilingual! But wait, there’s one more step.

6. Test the translation in an iPhone or iPad device

After all is done, you’ll have a multilingual application.

To test it with an actual phone, you’ll need to change the device’s language. You can follow Apple’s tutorial for switching iPhone languages.

You’re almost ready to release, just remember to test.

Here are some things you should look out for:

Pitfall	What can happen	How to fix
Translated strings overflow	German, French, Spanish and other European languages are normally 120% to 150% the size of English text. Asian languages are typically 50%-70%.	You should adapt the GUI to strings in different sizes. ICanLocalize iOS localization system checks string lengths and warns about strings that are either too long or too short.
Missing formatting characters	Many strings include place-holders for data, such as %s for text and %d for numbers. Other strings include HTML code. If the translation doesn’t include the same formatting, the application will fail.	Our translation system allows you to enter ‘must-have’ sequences. It will make sure that translations include the same sequences as the originals. Otherwise, you should manually review all strings and make sure that formatting characters match.
Out of context translation	It’s always possible that the translator didn’t exactly understand the meaning of a string. This is more frequent when applications include short and non-descriptive strings.	Send a full description of the application to the translator before starting the job. When it’s done, make photos of the application’s screen and send for final review. Adding comments to strings will help make sure you get excellent translation.

---

Troubleshooting

If strings in your Localizable.strings file are present in the translated file, but aren’t being localized on the device, check the character encoding of the file.

Unlike the iPhone simulator, the actual device only recognizes strings files that are formatted UTF-16. Always test your localizations on the device, as the simulator and the device do not always behave the same way.

The translated resource files you download from ICanLocalize are UTF-16 encoded. They’re contained inside gzip archives to make sure that your browser doesn’t alter them when you download.

Updating the translation when the iOS application evolves

ICanLocalize makes it easy to maintain your translations up to date. When the application evolves, new strings are created and existing strings may change.

To update the translations, run genstrings again to create a new Localizable.strings file. Then run ibtool again to generate new strings files.

Finally, upload the new resource files to your existing project in ICanLocalize. The system will detect new or modified strings and will only have them translated. You will need to pay only for updating the translation and not for doing it from scratch.

Note: when a string changes it needs to be translated again entirely. To reduce the cost of updating translations, we recommend splitting large strings into several smaller ones. This way, when you make a change, the part that needs to be translated again is smaller and costs less. Strings should be large enough to be clear on their own, but not too large, so that updating them isn’t expensive.

---

If you’re thinking about translating and republishing this tutorial, please contact us first. Tell us where you want to publish it and a few words about yourself.