Home » Tutorials » ICanLocalize – iPhone Apps Localization Guide

ICanLocalize – iPhone Apps Localization Guide

ICanLocalize – iPhone Apps Localization Guide

This guide will show you how to convert a single-language iPhone 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 iPhone application
  6. Testing the translation in an iPhone device

 

Need Translation for Your iPhone App?

ICanLocalize provides professional translation for iPhone apps.

Upload your resource file and get a final quote, right now.

iPhone resource file:

File format:

From language:

To language:

Already have translators?

You’re invited to use our translation system for free and cut down the time it takes to manage and coordinate translation work for your application.

Free translation system for mobile apps »

Introduction

The process of localizing an iPhone 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 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.

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 iPhone translation system can automatically remove duplicate strings from resource files, simplifying this task.

3. Collecting the embedded texts into resource files

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:

@"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 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.

5. Importing the translation to the iPhone 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 (click to zoom) Wrong place to drop the .xib file (click to zoom)
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.

6. Test the translation in an iPhone 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 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.

Troubleshooting

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.

Updating the translation when the iPhone application evolves

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.

Do you need translation for your iPhone application?

ICanLocalize offers professional translation optimized for iPhone applications. We can help you turn your iPhone app multilingual quickly, easily and at a low cost.

Expert translators, writing in their native languages will translate your application, helping you get more sales from around the world.

“We were impressed by the level of professionalism and attention to detail of the localizers we worked with. As we expand into new platforms and markets, we will continue to use ICanLocalize to ensure truly world-class results.”

“Not everybody speaks English so ICanLocalize made it possible to reach a wider market and Bump Technologies is addressing a wider audience now.”

“Initially I hadn’t intended to localize my app, thinking it was too hard or too expensive. But then I stumbled upon ICanLocalize. I had no idea translation could be made this easy.”


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.

56 responses to “ICanLocalize – iPhone Apps Localization Guide”

  1. Thomas Worrall

    Do you know how to add a localisation to an iphone app for a language that the OS doesn’t seem to support? I want my app to be available in welsh. I don’t mind if I have to add a GUI for switching it myself (since it isn’t in the OS’s list of languages), but I can’t seem to get it to load a cy.lproj bundle unless there is no other valid translation. I tried the tricks with registerUserDefaults for AppleLanguages. Any ideas?

    1. Amir

      Sorry, I don’t know how to do that, but I think that a better way to go about it is check with Apple how to generally handle languages outside of their standard list.

  2. Ben Harnett

    I have 2 questions:

    1) Can you localize an application for more than 1 version of english i.e. U.S english and U.K english?
    2) Can you localize an iphone app that doesn’t use nibs?

    Thanks.

    1. Amir

      1) Two English variants are not supported at the moment, but it’s something that we can add.
      2) What does the iPhone application use?

  3. iphone_tester

    Hello,
    Can I view the localized iPhone application without xcode but with the built-in iPhone simulator in the SDK?

    1. Amir

      The iPhone simulator lets you preview everything, including with translations.

  4. AppGuy

    Once uploaded you report I have 73 strings to translate but my files has over 200 in it. Why the discrepancy?

    1. Amir

      If you already have an account at ICanLocalize, open a support ticket and upload your resource file. I’ll have a look and see what’s wrong.

      You can open an account if you don’t have one here.

  5. Egon

    I’m stuck on localizing the xib files.

    When I try to execute the command “ibtool –strings-file fr.lproj/Example.strings -write fr.lproj/Example.xib en.lproj/Example.xib”, it gives me an error.

    “Illegal invocation. Try ‘man ibtool’ for more information. Not enough arguments provided; where is the input document to operate on?”

    I’m new to localizing, so I’m not sure what to make of this. When I look at the ibtool man page it doesn’t have the –strings-file option.

    Am I missing something?

    1. Rolf

      It should be:
      “ibtool -–strings-file fr.lproj/Example.strings –write fr.lproj/Example.xib en.lproj/Example.xib”
      not:
      “ibtool –strings-file fr.lproj/Example.strings -write fr.lproj/Example.xib en.lproj/Example.xib”

      You need two of “-” before strings-file and write.

      1. Martijn Croezen

        You might want to add the second – sign to the example you give at point 5.

    2. Al

      had the same problem… for me it worked with:

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

      Regards,
      Al

  6. Robert Wilkinson

    I have now seen lots of localization tutorials. Unfortunately I don’t want the user to have to go to the settings app to change the language. I want to make it a simple choice in the application itself and then change the language programatically.

    I haven’t seen anything that will tell me how to do that yet.

    Regards,
    Rob

    1. Eugene Stolin

      Same here. I am new to iOS development and looking for an example where application language can be changed in the application rather than in settings using localization. I would love to see one or just get a hint if it’s possible or not.

      Thanks in advance,

      1. Alex

        I think you’re misunderstanding – You speak English, so your phone is naturally set to the english localization, and all your apps run in english. None of them ever ask you to choose a language at startup, because your phone is already set to the language you speak. People who speak korean for example, will have their phones set to korean, they won’t have to go into settings to switch it, and they will expect your app to open up in korean without asking them. This isn’t an inconvenience, it is a convenience. Your language = phone’s settings language.

  7. pawi

    Hi,

    Is it possible to have my app running in a different language than the one that is set in the OS? I want to have a language switch in my app’s setting menu, where the user can e.g. select german for the app, while his system is running in english.

    From what I’ve already read, it seems it’s not possible without having my own localization mechanism…

    What do you think?

    Cheerz, pawi

    1. Amir

      I don’t think it’s possible, but also don’t see a reason for doing that.

      If the user didn’t set the language in the phone, which should a particular application display in that language?

      1. pawi

        Hi Amir,

        Thanks for your Answer. It was the customers request to do that :-) I life in Switzerland, we have People with iPhone’s language set to french / italian, working in the german part of Switzerland. I guess they want to use the app in german when working… Anyways

      2. Daniel

        Hi Amir,

        Please understand that we are living in the globalized world. So, this use case is the need of the time. I am a foreigner working in Japan with basic japanese skills, phone language is japanese. But i wish local app developers to release “foreigner only version of the same app” for german language in japan. Actually, it is frustrating to keep on changing phone language to view apps. I hope you pass on this request to Apple for future iOS releases.

        Thanks !!

  8. Sarah

    Hi

    I am wondering sthing: if I create resources for English, Italian and French, while the user’s OS is set to german for example. How can I let the code know it must take the English one by default ?

    tahnks a lot for your help that will be precious as I’m a beginner…

    1. Amir

      The phone chooses the right language according to the locale setting. All you need to do is provide several resource files. It will choose the best match according to th user’s language setting.

      I think that it will fall back to English for languages you’re not translating to.

  9. Sarah

    Thanks a lot for your quick feedback.
    also, there is a tracj I m exploring currently, the method NSLocalizedStringWithDefaultValue whish should enable me (as far as I understood) to specify a table of fallback languages french > spanish > english etc or whatever;
    hope it works! to be tested,
    With my best regards

  10. Jean-Bernard Ratté

    I had some issue when it came to replace all the english strings from my “.xib” file for the freshly translated “.strings” ones. I looked up the man page for ibtool and I saw some inconsistency from what is explained here.

    I came up with:
    ibtool –import-strings-file Example.strings en.lproj/Example.xib –write fr.lproj/Example.xib

    1. Jean-Bernard Ratté

      It seems that the form strip a dash “-” when data get summited for validation. Consider that ibtool properties takes two leading dashes.

  11. Crazer

    Hey Guys,

    great article. But I got a little problem. The localization of the embedded strings works fine. But the xibs stay in my default language. I checked them in the Interface Builder and the translation looks good but when I test it in the simulator it only shows the default language.
    I checked the tutorial twice and it all looks ok. I can’t find any mistake I could’ve made.

    1. Crazer

      Ok, I just tested it on my iPhone and there it works.
      Thanx anyway for the tutorial.

  12. Travis

    For some reason, when I switch languages, and run my app again from the home screen (not Xcode), it crashes. If I reboot my ipad with the different language applied, and open my app, everything is fine. It looks like NSLocalizedString() is the problem, but not sure.

    1. Amir

      Maybe problem in formatting characters of some strings in the translation?

  13. Ryan

    Hello all,

    I am getting the following error when attempting to create a .xib file from a translated .strings file:

    com.apple.ibtool.errors

    description
    Not enough arguments provided; where is the input document to operate on?

    I am using the following commands:
    btool –generate-strings-file English.lproj/Spanish.strings English.lproj/English.xib
    ibtool –import-strings-file Spanish.lproj/Spanish.strings English.lproj/English.xib –write Spanish.lproj/Spanish.xib
    —-also tried:
    ibtool –strings-file Spanish.lproj/Spanish.strings English.lproj/English.xib –write Spanish.lproj/Spanish.xib

    My process for the changes was to generate the .strings file and then replaced the quoted tags using xcode. Any ideas as to why I am getting this error? I know I typed the path to both input files (.string and original .xib) correctly so I don’t know why it says there is no input argument to operate on?

    Thanks

  14. Simon Bogutzky

    For me the following is working:

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

    (before write are write are two — signs)

  15. Pepyn Hoff

    Hi,

    I am trying to localize my content which is build in X code itself in my viewcontroller.m file… I tried this tutorial with it but I can’t get this to work! So please could you give me some assistance? please contact me or add me on Skype…
    pepyn18 is the Skype name

    Hope to hear from you!

  16. Pedro Paulo

    It seems that the parameters in the tutorial are in the wrong order:

    This doesn’t work:
    ibtool –strings-file Portuguese.lproj/DetailView.strings English.lproj/DetailView.xib –write Portuguese.lproj/DetailView.xib

    This works
    ibtool –strings-file Portuguese.lproj/DetailView.strings –write Portuguese.lproj/DetailView.xib English.lproj/DetailView.xib

  17. ravi bukka

    Hi,

    I am working for iPhone application development and I came to know that I can extract strings from .xib by using IBTOOL and strings from resource files (.m) using gestring but my problem is how can extracts a strings from .plist files in order to translate those strings my self.

    I don’t need any translator for this, So can you please tell me is any way to extract the strings from .plist .

    Thanks & Regards,

  18. Ricibald

    Great guide! You can localize automatically your nibs without duplicating them following this simple guide:

    http://programminghacks.net/2011/06/03/ios-nib-localization-in-localizable-strings/

  19. Jean Claude

    what about the description of the functionalities of the app on the App Store? Do we need to have this translated?

    1. Amir

      You certainly need to translate these, so that people can find your app when searching in different languages. You can do this by manually adding a string to the project in ICanLocalize, or adding the string to the .strings file before creating the project.

  20. Christian Pappenberger

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

    This code isn’t working!

    Can someone please tell me what the right way is to do that?

    Would be great;)

    Greetings from Germany

    1. Dou Hai Tao

      Can work with this:

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

      1. Dou Hai Tao

        double “-” sign

  21. Prashant Chaudhari

    I don’t want to pick up the language from the device setting but from the app specific settings so that the user can run my app in a language different from the device’s language. However the issue is if the app is running and then the user changes the app settings, some of my screen are already in first language and the newer screens load with the newly selected language. I cannot quit the application so that all strings are reloaded since it is not recommended by Apple and there are chances of it getting rejected for this.

  22. Radorbit

    [SOLVED]:

    None of the above solutions works except for this:

    ibtool –strings-file zh_hans.lproj/Example.strings –write zh_hans.lproj/MainWindow.xib English.lproj/MainWindow.xib

  23. Radorbit

    Ignore the previous comment: This one is the correct

    ibtool –strings-file zh_hans.lproj/Example.strings –write zh_hans.lproj/MainWindow.xib English.lproj/MainWindow.xib

  24. Radorbit

    It appears that when posting comment, “–” (two hyphens) is converted into a single. Hence, anyone referring to above comment must also ensure that there are two “–” (two hyphens) before “strings” and “write” in the statement:

    ibtool –-strings-file zh_hans.lproj/Example.strings –-write zh_hans.lproj/MainWindow.xib English.lproj/MainWindow.xib

  25. Hugo

    When trying to move some (of around 50 just 4 are giving me this error) .xib into its localization folder an xCode error arises:

    “Interface Builder could not open the document “Example.xib” because it does not exist.”

    It seems the .xib file it is just accepted at the original folder…

  26. benefit

    Hi

    How can I make the localization independent on the OS settings. For example, if the device language and region is en_US, I want the user to be able to set the app to work using Arabic localization.

  27. Rich Rygg

    What is the complete list of localization languages supported by Apple iTunes App Stores?

  28. Jorgen

    I have a strange problem.
    I have an app with two targets, basically to be able to change the icon in different stores. One of them work fine, but the other crashes if the language is set to Swedish. Any other language and it works fine (Spanish, Portuguese, Korean etc.)
    Any idea what can cause this?

  29. Andrew Blake

    Thanks for the info!
    That’s very informative and useful!
    Though, ibtool –strings-file zh_hans.lproj/Example.strings –write zh_hans.lproj/MainWindow.xib English.lproj/MainWindow.xib doesn’t work either…

  30. softwaremac

    I’s very easy, It works with: ibtool –strings-file zh_hans.lproj/Example.strings –write zh_hans.lproj/MainWindow.xib English.lproj/MainWindow.xib

  31. John Doe

    I’m new to iOS development, coming from Android background. I’m finding the need to duplicate the entire .xib for localization a bit excessive and a maintenance headache (think of all the problems of code duplication).

    Is there’s a way of specifying the strings within the .xib by referring to the key to the localized string directly. This is possible in Android.

    1. Amir

      I don’t think so. Apple intended it to work this way. Google lets you have an XML with different languages and Apple prefers individual files, but it’s not so bad. If you translate with us, you’ll get the .strings files in all different languages, with the correct names. Then, you just drag it to the project and the rest goes pretty easily.

      I would recommend to stay with Apple’s workflow, even if it requires some compromises. Creative alternatives may easily break later, just causing you more work.

    2. Raymond Cheney

      I think you need to localize your app from inside the app. You can use the method localizedStringForKey which you can find inside the macro NSLocalizedString and use a language bundle you created (like en.lproj or es.lproj). You can follow this step by step tutorial I found here

      http://codehunk.blogspot.in/2012/09/how-to-localize-internationalizationi18.html

      I hope this is exactly what you need. And yes I have also worked on Android and it does gets a little tricky in iOS initially.

    3. Ian Wilkinson

      Read up on Apple’s new Auto-layout feature for iOS 6.
      http://developer.apple.com/library/mac//ipad/#/documentation/UserExperience/Conceptual/AutolayoutPG/Articles/Introduction.html
      With the correct layout constraints applied, this should allow you to write a single xib, which adjusts correctly for each localization.

  32. Ian Wilkinson

    Read up on Apple’s new Auto-layout feature for iOS 6.
    http://developer.apple.com/library/mac//ipad/#/documentation/UserExperience/Conceptual/AutolayoutPG/Articles/Introduction.html
    With the correct layout constraints applied, this should allow you to write a single xib, which adjust correctly for each localization.

  33. saga

    Will Xcode is applicable to localize my apps to Chinese language and will that translates to Chinese for my apps.

    1. Laura

      Yes, Apple’s code fully supports Asian characters, including Chinese.

Leave a Reply