If you're new here, you may want to subscribe to my RSS feed or follow me on Twitter. Thanks for visiting!
This is a guest post by Sean Berry, a mod on the forums and the developer of Algebra Touch.
Me Gusta Localization!
Although the English-speaking App Store market is the largest, there are still plenty of other iPhone users in the world and you can greatly increase their user experience by supporting their native language.
The good news is Apple has made it very easy to make your apps work with multiple languages through some API calls and built-in Xcode support. The process of doing this is called localization, and that’s what I’ll be showing you how to do!
In this tutorial, you will be localizing a sample app I prepared called iLikeIt which was inspired by the rage comics in Ray’s post about in-app purchases. The app is very simple – when you tap ‘You like?’ a face appears, scales up, and fades away.
But right now it’s English only – so vamos a traducir!
This tutorial will be using Xcode 4, so if you haven’t upgraded already, why not use this as an excuse to do so?
Getting Started
The first step is to download the iLikeIt starter project that we’ll be localizing in this tutorial.
Compile and run the app, and you should see the following appear:
We have 3 things to localize here:
- Title text: ‘Hello!’
- UI Element: ‘You like?’ button
- and finally the image (it has text!)
Separating text from code
Like most projects, this project has some hardcoded strings in the code. We need to pull all of these hardcoded strings into a separate file so we can localize them.
The way you do this in Xcode is create a “.strings” file to contain all of the strings your projects needs. Then you’ll replace the hardcoded strings with a function call to look up the appropriate string from the “.strings” file based on the current language.
Let’s try this out. Select the iLikeIt group in Xcode, and go to File\New\New File. Choose iOS\Resource\Strings File, and click Next, as shown in the screenshot below. Name the new file Localizable.strings, and click Save.
Note that Localizable.strings is the default filename iOS looks for when dealing with localized text. If you don’t use this, you’ll have to specify the name of our .strings file every time.
The format for the strings file is:
"KEY" = "CONTENT";
So for our ‘Hello!’ text add in:
"TITLE" = "Hello!";
Now switch to iLikeItViewController.m, and find the viewDidLoad method. Right now it sets the text as:
self.titleLabel.text = @"Hello!"; |
We want it to instead read from our .strings file. To do that, change the current line to use a macro called NSLocalizedString as shown below:
self.titleLabel.text = NSLocalizedString(@"TITLE", nil); |
If you’re curious what the NSLocalizedString macro does, control-click on NSLocalizedString and choose Jump to Definition. You’ll find that it’s defined as follows:
#define NSLocalizedString(key, comment) \ [[NSBundle mainBundle] localizedStringForKey:(key) value:@"" table:nil] |
So basically, it’s using the localizedStringForKey method to look up the string for the given key, in the current language. It passes nil for the table name, so it uses the default strings filename (Localizable.strings). For full details, check out Apple’s NSBundle Class Reference.
One other thing to note. The macro takes a comment as a parameter, but seems to do nothing with it! This is because instead of manually typing in each key/value pair into the Localizable.strings value like we’ve been doing, you can use a tool that comes with the iPhone SDK called genstrings to do this automatically (which can be quite convenient for large projects).
If you use this method, you can put a comment for each string that will appear next to the default strings as an aid for the translator. For example, you could add a comment indicating the context where the string is used.
Enough background info – let’s try it out! Build and run your project, and it should say “Hello!” on the main screen just as before. But where’s the Spanish? Now that we’re set up it’s a cinch.
Adding a Spanish Localization
To add a Spanish localization, start by selecting Localizable.strings, and open up the Info pane. You can do this by selecting the third tab in the View section in the top toolbar, and selecting the first tab in the top section, as shown in the screenshot below.
To add support for another language, simply click on the ‘+’ in that ‘Localization’ pane on the right. The first time will create a localization for English. Note it might deselect Localizable.strings after you click it, so select Localizable.strings again, click the ‘+’ button again, and choose ‘Spanish (es)’ from the dropdown.
At this point, Xcode has set up some directories containing a separate version of Localizable.strings for each language you selected, behind the scenes. To see this for yourself, open your project folder in Finder, and you’ll see the following:
See ‘en.lproj’ and ‘es.lproj’? They contain our language-specific versions of files.
‘en’ is the localization code for English, and ‘es’ is the locazliation code for Spanish. If you’re curious, here’s the full list of language codes.
When iOS wants to get the English version of a file, it will look in en.lproj, but when it wants the Spanish version of a file it will look in es.lproj.
It’s that simple! Put your resources in the appropriate folder and iOS will do the rest.
Go back to Xcode and click on the arrow next to Localizable.strings so it shows the sub-elements. You’ll see now we’re working with two versions of this file:
To change the text for Spanish, select ‘Localizable.strings (Spanish)’ and change the text to read:
"TITLE" = "Hola!";
Your app is worldly now! Let’s make sure it worked…
To make your simulator show Spanish, go into Settings.app and choose General -> International -> Language -> Espanol.
Delete the app and select Project\Clean to get a fresh build and install. When you build and run you should see Hola!:
Adjust UI Elements
The next thing to localize is that button text. For Spanish let’s have it say ‘~Es bueno?~’
The issue here is that we want our button border to be relatively tight around the text.
This wasn’t an issue with our title label because there was no constraint on its width, but here we’ll need to adjust the size of the button to make it look nice.
If we simply edit the text in viewDidLoad it will look bad, check it out:
Unacceptable! So let’s add a localization to our xib and make the button bigger in Spanish.
Select iLikeItViewController.xib and in the info pane on the right, click the ‘+’ button to add a Localization and choose Spanish. Note you may need to scroll down in the Info pane because it shares that side with some Interface Builder content.
Now we have copy of iLikeItViewController.xib in our Spanish folder (es.lproj). Select iLikeItViewController.xib (Spanish), and edit the button text in that version to say ‘~Es bueno?~’ (it should resize the button by default).
Tip: To add special chararacters on the Mac such as upside down question marks, one way is to go to System Preferences\Keyboard, and select “Show Keyboard & Character Viewer in menu bar”. You will see a new option in your menu bar as shown below:
You can use this to browse through special characters and double click them to add them into any app, including Xcode.
Once you’ve set up your label, delete the app and select Project\Clean to get a fresh build and install. (You might even have to close and reopen the project in Xcode for Xcode to pick up the changes). Then build and run your app to see the following:
Images
Since we have text in our image we need to localize it. Having some English in an otherwise Spanish app would look amateur.
Select ‘ilike.jpg’ and add a localization for Spanish (you’re an old pro at this now!)
Check out the project folder. ‘ilike.jpg’ has been added to the English folder (en.lproj) and then copied to the Spanish folder (es.lproj). To make a different image show up for the Spanish version, we simply overwrite the image in the Spanish folder.
Download this image:
I’ve also included it in the starting project, saved as megusta.jpg.
Rename it to ilike.jpg and move it into the Spanish folder (es.lproj), overwriting the copied English version.
Clean and rebuild and you should be done!
Congrats! That’s the bulk of localization.
Gratuitous Bonus
For a final bonus, say you want to translate the name of the app. Your Info.plist has a special file in which you can put string overrides that need to be different from language to language called InfoPlist.strings. So to make the app name different for spanish, localize Supporting Files\InfoPlist.strings and insert the following in the Spanish version:
"CFBundleDisplayName" = "Me Gusta";
That will change the name of the app as it appears on the Springboard.
…which brings up something to consider when localizing. The English version had a prefix of ‘i’ (as a nod to Apple’s naming convention).
When translated to Spanish that joke is lost. However, it was a terrible joke and the Spanish version is better for it!
Where To Go From Here?
Here is a sample project with all of the code we’ve developed in the above tutorial.
Now that you know the basic technique of localizing an iPhone app, try to keep it in mind when designing your next app. It could be quite easy and your non-English speaking audience will be thankful!
For the actual translation, you might be able to get away with using Google’s free translation service athttp://www.google.com/translate. But I would only use that for simple words in buttons or labels. A more professional option is myGengo, a ‘matchmaking’ type service I’ve had success with in the past. You submit a translation job and any number of freelancers can accept and translate it for you. The turnaround time is fairly quick (all of my jobs were done within 24 hours) and it’s affordable.
If you have any questions, or advice for others localizing their apps, please join in on the forum discussion below!