ONE AND ONE MAKES TEN

Motivation

When I first started out localizing my first iPhone application, I went bananas. Unlike most of the developer resources available for programming on an Apple infrastructure, this feature seemed so confused in documentation and poorly understood by the community. All I wanted was to have multiple languages on my application, relative to the user’s preferences, just by using NSLocalizedString, and editing the translation files.

Please note that there is a whole lot more to localization beyond having different languages on your application. I’m not going to cover that on this post. I’m also not going to talk about localizing XIB files.

Goal

This guide will help you localize strings included in your code (using NSLocalizedString) as well as making the translation process incremental (without ever losing the previous translations made).

Problem

I’m going to talk about the surprise I had when I started localizing my application: the Localizable.strings files that gets generated using Apple’s tool – genstrings – overwrites the previous translations, instead of properly merging them with the new changes. Since I needed to translate as I was developing the application, this meant that I had to merge the files by hand at every step of the translation process (always being careful not to lose the previous translations). This just wouldn’t work.

Solution

And so, I’ve made a Python script that does just what we need: it generates new translation files, merges them with the previous translations and keeps copies of all those steps, just in case anything goes wrong.

Step by Step

Here’s how it works:

1. go into your XCode project folder and create xx.lproj folders inside, one for each language you would like (using ISO 639-1 and ISO 639-2 codes). For example, to have your application in English, French and German, you would create three folders: en.lproj, fr.lproj and de.lproj;
2. put my script localize.py inside the XCode project folder (it is being hosted on my github repository);
3. simply run ./localize.py on the Terminal, from the XCode project folder and your files will be created on the first run, and merged on subsequent runs.
4. after running the script for the first time you should have your Localizable.strings files inside each language folder. To make them work with your application, just add them to your XCode project.

Notes

The script always leaves two files behind, per language: Localizable.strings.old and Localizable.strings.new. These are the two files that got merged to create the brand new Localizable.strings file. They might come in handy for some troubleshooting. By not adding them into the XCode project and (if applicable) by adding them onto your favourite revision control program’s ignore list, they cause no trouble at all.

I hope this helps someone, just like it has been helping me ever since I created it.

If you have any comments, questions, bug reports, please let me know in the comments section.