Generally most iOS and macOS developers agree on one thing: Localizing XIB files and Storyboards is a pain. It requires you to deal with Interface Builder Object IDs, having your translations spread out across multiple
.strings files, files getting out of sync, and more. It's a hassle, and it almost makes you give up and do everything in code.
The biggest problem with the default way is that you have to reference your views from your translation files, and you have to do this using IB Object IDs. This is counterintuitive, and it really feels like something Apple could have improved on.
Localize-xibs improves this by flipping the default workflow around, so now you can refer to your translations from Interface Builder!
It offers the following benefits:
- You can keep all your translations in one file per language, instead of different string files throughout your project.
- It allows you to reference your translations directly from Interface Builder, no more dealing with Object ID's.
- You immediately get a visual overview of what is translated and what not.
- Compile time checking for missing translations.
- Add all your translations in centralized
.stringsfiles in your project, for example:
- In the Xcode file inspector, configure your XIBs and Storyboards to be localized using "Localizable Strings".
- Wherever you normally enter text using Interface Builder, you can reference your translation using:
- In the root of your project run
localize-xibs, passing it a list of all your centralized translation files. For example:
localize-xibs \ MyProject/Resources/en.lproj/Localizable.strings \ MyProject/Resources/de.lproj/Localizable.strings
Let's walk through the three simple steps to localise a Storyboard. The steps are exactly the same for localising a XIB file. I'm going to assume you've already set up your Xcode project for multiple languages and "Base Internationalization"
In your Xcode project, add a
.strings file that will hold all the translations for your entire project. In this example I will call it
Localizable.strings. After you added the file, go to the file inspector and click "Localize...".
Select a language from the dropdown and after that make sure that you check all checkboxes for the languages in your application.
Now, you can add your translations to the
Localizable.strings files. For example:
/* en.lproj/Localizable.strings */ "my_title" = "This is the title"; "my_description" = "This is the description";
/* nl.lproj/Localizable.strings */ "my_title" = "Dit is de titel"; "my_description" = "Dit is de beschrijving";
For the Storyboard we follow the same steps to localize it by clicking the "Localize..." button in the file inspector. Make sure you configure it to use "Localizable Strings" as the localization strategy.
In the storyboard, you can now refer to your translation keys by prefixing them with "t:". Let's add two labels with the texts:
In the root of your project run the
localize-xibs command, passing all the
Localizable.strings files that contain your translations. Localize-xibs will automatically detect your locales, and localize all your XIBs and Storyboards for you.
localize-xibs \ MyProject/Resources/en.lproj/Localizable.strings \ MyProject/Resources/nl.lproj/Localizable.strings
That is all there is to it. From now on you can just add translations to the
Localizable.strings files, and refer to them from Interface Builder using the
Instead of having to run
localize-xibs every time you update or add a translation, you can have Xcode do this for you by adding a Run Script build phase.
That way you can just add translations to your centralized files, and your XIBs and Storyboards will automatically be updated on each build. An added benefit is that it ties in with Xcode, showing you build warnings or errors when you reference a missing translation.
Simply add a
Run Script phase with the localize-xibs command, optionally using the
--strict flag. Make sure it is positioned before the "Copy Bundle Resources" phase.
localize-xibs --strict \ MyProject/Resources/en.lproj/Localizable.strings \ MyProject/Resources/de.lproj/Localizable.strings