loading...
Cover image for Easy XIB and Storyboard localization

Easy XIB and Storyboard localization

wvteijlingen profile image Ward van Teijlingen Updated on ・3 min read

GitHub logo wvteijlingen / localize-xibs

Easy XIB and Storyboard localization without having to deal with Object IDs and multiple string files

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.

Introducing localize-xibs

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:

  1. You can keep all your translations in one file per language, instead of different string files throughout your project.
  2. It allows you to reference your translations directly from Interface Builder, no more dealing with Object ID's.
  3. You immediately get a visual overview of what is translated and what not.
  4. Compile time checking for missing translations.

You can reference your translations directly from Interface Builder

TL;DR: Usage

  1. Add all your translations in centralized .strings files in your project, for example:
    • MyProject/Resources/en.lproj/Localizable.strings
    • MyProject/Resources/nl.lproj/Localizable.strings
  2. In the Xcode file inspector, configure your XIBs and Storyboards to be localized using "Localizable Strings".
  3. Wherever you normally enter text using Interface Builder, you can reference your translation using: t:my_translation_key.
  4. 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

Example: Localizing a Storyboard

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"

1. Adding your translations

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

Alt Text

Select a language from the dropdown and after that make sure that you check all checkboxes for the languages in your application.

Alt Text

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";

2. Updating your Storyboard

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.

Alt Text

In the storyboard, you can now refer to your translation keys by prefixing them with "t:". Let's add two labels with the texts: t:my_title and t:my_description.

3. Running localize-xib

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's it!

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 t: prefix.

Spice it up: use as Xcode Run Script

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.

For example:

localize-xibs --strict \
  MyProject/Resources/en.lproj/Localizable.strings \
  MyProject/Resources/de.lproj/Localizable.strings

For

GitHub logo wvteijlingen / localize-xibs

Easy XIB and Storyboard localization without having to deal with Object IDs and multiple string files

Posted on Apr 5 by:

wvteijlingen profile

Ward van Teijlingen

@wvteijlingen

Freelance developer with over 10 years experience building for web and mobile.

Discussion

markdown guide