This guide will show you how to convert a single-language iPhone application, built with Xcode, into a multilingual application.
- Making Resources Localizable in Xcode
- Localizing Interface Builder files
- Collecting embedded texts into resource files
- Translating the resource files
- Importing the translation to the iPhone application
- Testing the translation in an iPhone device
The process of localizing an iPhone application involves these steps:
- Getting your resource files ready for localization.
- Collecting all the texts used in the application in resource files.
- Translating the resource files.
- Integrating the resource files back in the application.
Since iPhones are multilingual by design, once your application is available in multiple languages, the phone already knows what to do. It will display the GUI texts in the right language, according to the phone’s language setting.
All iPhone applications are built using Unicode texts, encoded as UTF-16. The iPhone simulator supports this format and will allow you to preview your translated application.
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.
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 iPhone translation system can automatically remove duplicate strings from resource files, simplifying this task.
Normally, iPhone 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:
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).
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).
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 iPhone resource files, which allows translating iPhone 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). Then, translators will translate just the strings.
Professional (human) translators, who have ample experience in localizing iPhone applications will translate 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 iPhone 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.
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 iPhone application should now run multilingual! But wait, there’s one more step.
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 iPhone 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.|
If strings in your Localizable.strings file are present in the translated file, but aren’t being localized on the iPhone, check the character encoding of the file.
Unlike the iPhone simulator, the iPhone 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.
ICanLocalize makes it easy to maintain your translations up to date. When the iPhone 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.