Polyglot allows localizing the user interface straight from the Storyboard/XIB files in Interface Builder.

It provides extensions to common UI elements to set the localized text in Interface Builder. For instance, a UILabel will display a "Text Key" property. When a value is set, Polyglot will call NSLocalizedString using the given value and set it to the label's text property.

Why Polyglot?

There are already several ways to internationalize the UI:

• Traditionally, we would duplicate each storyboard for every locale. This makes the storyboards really hard to maintain.
• It is a common practice to define outlets for every UI element and set the text using NSLocalizedString. It adds unnecessary outlets and lots of boilerplate code.
• Base internationalization is a powerful tool to localize the UI, but let's face it, it is not the optimal solution. The generated string files are hard to maintain and it is not developer friendly when making changes to the storyboard.

Polyglot doesn't try to replace these tools, but provide a complementary approach to the localization process. It is a clean and simple solution compared to creating outlets. It is also easy to maintain, while keeping control of the strings file.

Requirements

• iOS 8.0+ / Mac OS X 10.9+
• Xcode 7.0+

Setup

CocoaPods

Make sure that you are using the latest CocoaPods version.

Then add Polyglot pod to your podfile. This is an example of a podfile for an iOS app:

platform :ios, '8.0'
use_frameworks!

pod 'PolyglotLocalization'

Notice the use_frameworks! line, it is important that you include it. Note also that the minimum platform versions needs to be respected as specified in the Requirements above.

Finally, don't forget to update your pods and open the generated xcworkspace file:

$ pod install

Other

There are other ways to include Polyglot in your project. Polyglot is a set of extensions written in Swift so you may as well copy the files to your project (not recommended), or add the project as a dependency...

Just note that the project can not be included as a static library since Interface Builder will not recognize the inspectable properties in that case.

Usage

Basics

Once Polyglot is set up, open your Storyboard of XIB file. Select a UI element that displays some text (a UILabel for example), you will see a property named "Text Key" in the property inspector. Set the following value to the "Text Key" property: hello_wolrd.

Now you will have to add the corresponding value to the Localizable.strings file:

"hello_wolrd" = "Hello World";

You can now run the app and the label should display Hello World.

Property naming

The properties that can be localized with Polyglot are named as the original properties followed by key:

• Text -> Text Key
• Title -> Title Key
• Placeholder -> Placeholder Key

This way, it is easy to recognize what properties will be localized in each case.

Table-based keys

NSLocalizedString() has a tableName attribute that allows using a specific '.strings file'. Polyglot provides the following format in order to specify the table name:

[table_name].string_key

So if you want to use the 'field_title' key from the 'Common.strings' file, you can set the following in Interface Builder:

[Common].field_title

CSV Properties

When a list of elements needs to be localized, the keys are specified in CSV (Comma Separated Values). This is the case for segmented controls for example. The corresponding properties are named accordingly: Title KeysCSV.

The list of keys is obtained by taking the comma separated values. The values are trimmed, so spaces next to the commas are ignored.

Then, each of the keys is used to localize the corresponding element. For instance, the fist key will be used to localize the fist segment and so on. The following example would modify the titles of the fist three segments:

segment_one, segment_two, segment_three

In case there were more than three segments, the reset would not be modified. The same way, we can leave empty elements to ignore certain elements. The following example will only modify the first and the third segments' title:

segment_one, , segment_three

UIButton

UIButton allows setting a title text for each state. In response to this, Polyglot provides one property for each state: default, highlighted, selected and disabled.

If we just need to assign one title for all states, we will only assign Default Title Key and leave the rest empty.

Advanced

Custom key management

Polyglot allows you to configure how keys are handled. You need to modify the Polyglot.localizer to set up your own implementation.

By default, it parses the table and the key as specified above in "Table-based keys". This is implemented in the TabledLocalizer class.

Let's say we want to verify that every key is actually translated and throw a fatal error otherwise. We configure Polyglot like this:

        Polyglot.localizer = TabledLocalizer { key, tableName in
            let result = NSLocalizedString(key, tableName: tableName, value: "{NOTFOUND}", comment: key)
            if result == "{NOTFOUND}" {
                fatalError("Poliglot: Key '\(key)' not found")
            }
            return result
        }

We need to run this code when the app is launched, before the UI is loaded. For iOS, it will typically go in the UIApplicationDelegate.application(application, didFinishLaunchingWithOptions) implementation. While for MacOS apps, you should override awakeFromNib in your NSApplicationDelegate and place the code there.

    override func awakeFromNib() {
        Polyglot.localizer = ...
    }

And don't forget to import the module:

    import PolyglotLocalization

One More Thing...

If you like this library, make sure to share it!

License

Polyglot is released under the MIT license. See LICENSE for details.