How to set translation key from Storyboard on iOS?

Posted on Posted in iOS


In this post, I will show how to add simple localization support to iOS application and how to use it from Storyboard. In Apple’s documentation you can read an article Localizing Your App. However, the described ‘offical’ way to translate Storyboards generates some crazy entries. Even more, crazy things begin when you want to update translations.

Sample Storyboard Translations
Sample Storyboard Translations (.strings file)
So what’s the problem with this solution?
  1. Usually from a localization team or your client you will get translations as pairs: TranslationKey – Translation. It may be an XML file or something else, but anyway most likely no-one will be interested in delivering and maintaining a file like above (actually after exporting it you will get .xliff file which is even less readable, especially for people not related with IT).
  2. Redundancy! Many translations will occur multiple times and it makes them hard to change.
  3. When you add new controls to Storyboard, they don’t appear in .strings file automatically. This feature is not even available in Xcode, you have to do some ugly workarounds: Is it possible to update a localized storyboard’s strings?
  4. Try to move a ViewController from one Storyboard to another and your nightmare will begin. Now not only .strings files for two Storyboards are incorrect, but also .xliff file which you somehow managed to get after hours of convincing your localization team.


How to implement a better solution?

The idea is to create a single file per language with translations (Localizable.strings) which is supported by default by Xcode. Then we will prepare a set of basic controls to support translation keys from Storyboard.

Actually, if it’s better you have to decide on your own. There are of course some trade-offs, but it seems to be a reliable solution that shouldn’t cause a headache in case of changes in translations or Storyboards.

Add support for localization

1. Add Localizable.string

Click on File -> New -> File -> Select “Strings File” -> Name it “Localizable” and Save.

Add Localizable.string
Add Localizable.string


2. Enable localization for this file

Now you need to enable localization for Localizable.strings. I recommend to put this file in some folder like “Strings”, because later there will be generated folder for each language. To enable localization just select the file and click on “Localize…”.

3. Choose languages

Select your project and add languages that you want to support.

Choose languages
Choose languages

When it asks to choose reference files, deselect all but “Localizable.strings”.

Choose files
Choose files


4. Add translations

Ok, so everything is ready. Now you can add your translations. If you have translations in XML from your localization team, then you will need to prepare a simple script to convert it to format: “TranslationKey” = “Translation”;

Localizable files
Localizable files


5. Use them from code

So for now we managed to add translations in multiple languages and we should be able to use them from code like this:


6. Change language

To verify if your localization works, you will need to switch your phone to another language. Also, you can do that from Xcode, just go to Product -> Scheme -> Edit scheme and select Application Language:

Change application language in Xcode
Change application language in Xcode



We already have working translations, but we need to use them from Storyboard to avoid adding outlets to all controls and setting translations in ViewController. Also it would be nice to have some extension to avoid writing every time something like NSLocalizedString(“HelloWorld1”, comment: “”).

1. String extension

By using this extension, you won’t be able to use genstrings command-line tool to create translation files from translation keys used in code. You have to decide if you need it. If you get translations from the localization team in a specific format, then probably you won’t need to use this tool.

Now you can use translations in code in more readable way:


2. Set of controls to support translation key

This simple implementation will allow you to add translation keys from Storyboard for UILabel and UIButton. Of course you can add implementation for more controls if you need.

3. Usage from Storyboard

The only thing you need to do is to set Custom Class for your controls on Storyboard or if you have custom controls you have to change their base class in code. After that you will be able to set Translation Key on Storyboard. This implementation also detects very fast if translation key is not set and throws an exception.

Set Custom Class
Set Custom Class
Set Translation Key
Set Translation Key



Now you are able to use translation keys both from Storyboard and code. When you receive the updated file with translations, the only thing you need to do is to replace your current translations. This solution seems to be more flexible than the one described by Apple, especially since you can use one translation in multiple places and you don’t have to worry about updating Storyboards.