Easy XIB and Storyboard localization
Tags: ios, translations, xcode, swift
Published: 2020-04-05 15:32:39

{% github wvteijlingen/localize-xibs no-readme %}

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.
1. It allows you to reference your translations directly from Interface Builder, no more dealing with Object ID's.
1. You immediately get a visual overview of what is translated and what not.
1. Compile time checking for missing translations.

![You can reference your translations directly from Interface Builder](https://dev-to-uploads.s3.amazonaws.com/i/gqhjw4bprq02ilntgibe.png)

## 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`
1. In the Xcode file inspector, configure your XIBs and Storyboards to be localized using "Localizable Strings".
1. Wherever you normally enter text using Interface Builder, you can reference your translation using:
   `t:my_translation_key`.
1. In the root of your project run `localize-xibs`, passing it a list of all your centralized translation files. For example:

   ```bash
   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](https://dev-to-uploads.s3.amazonaws.com/i/w5rz223fm7jc37ipr9hm.png)

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

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/hc424wwqnr9it8jmerxl.png)

Now, you can add your translations to the `Localizable.strings` files. For example:

```strings
/* en.lproj/Localizable.strings */
"my_title" = "This is the title";
"my_description" = "This is the description";
```

```strings
/* 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](https://dev-to-uploads.s3.amazonaws.com/i/txufm27z88pliq1phvt9.png)

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.

```bash
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:

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

For 
{% github wvteijlingen/localize-xibs no-readme %}