smholloway / polyglot Goto Github PK

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.

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

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

Make sure that you are using the lates 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

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 reconize the inspectable properties in that case.

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 propery named "Text Key" in the propery inspector. Set the following value to the "Text Key" propery: hello_wolrd.

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

"hello_wolrd" = "Hello Wold";

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

The properties that can be localized with Polyglot are named as the original properties followd 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.

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 correponding 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 correponding 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 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 asign one title for all states, we will only assign Default Title Key and leave the rest empty.

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

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