Lokalise iOS framework

Updated 11 days ago ​by Nick Ustinov

This guide assumes that you have already prepared your iOS app for localization. Need help with this? Read our Getting started with iOS localization tutorial. If you are experienced with iOS localization, give it a quick look as well, just to be on the same page.

Introduction

Lokalise iOS framework comes as CocoaPod library and can be easily integrated into your Objective-C or Swift project. Once the translations are finalized in Lokalise editor, you generate bundle using Lokalise Download page (or use the API request to generate it). As end user opens your app on his device, the framework requests latest version of the bundle from our servers and if found downloads and stores it locally.


Features

  • Over-the-air (OTA) localization
  • Instant UI language switching 
  • Test localizations (using prerelease bundles)
  • NSBundle swizzling for transparent integration
  • XIB and storyboard localization


Limitations

System localization

Some of the system inteface objects might not get translated (search bar for example) when changing application language at runtime.

UI localization

In case you choose not to use swizzling, storyboards and nibs will not be localsed using our framework. 


Getting started

Step 1: Set up your project in Lokalise

If you have not done so yet, add new project in Lokalise, upload source language files you may have (or just add keys straight in Lokalise's editor if it's a new app you are building). Take a note of project ID, that can be found in project settings, usually it looks like this:

3281927757690217f560f6.71199070



Step 2: Generate the bundle

Go to Downloads page in Lokalise, select "Lokalise iOS framework" as the format and click Build only button to generate the bundle. You will be automatically taken to the bundle versions management page at projects settings. Leave the switches as is for now, see details in Managing bundles section.

Make sure to always include fresh Localizable.strings in your project when releasing the app. There are various ways to automate this process, please refer to Part III - Integrating with your project in Getting started with iOS localization tutorial.


Step 3: Install Lokalise framework

To install using CocoaPods simply add this line to your Podfile

pod 'Lokalise', '~> 0.3.0'

Dependencies will be installed automatically. If you would like to install manualy, download Lokalise.framework and add it to your project (you will also need to add ZipZap).



Step 4: Set up your project

To connect your application to your Lokalise project you need to add a dictionary and specify provided API access token and project ID to Lokalise framework. 

  1. Create a dictionary named Lokalise at the root of your ProjectName-Info.plist file.
  2. Add string API Token to Lokalise dictionary and set value to your API access token (it can be found under Account in Lokalise).
  3. Add string Project ID to Lokalise dictionary and set value to ID of the project you want to use (see project ID in project settings in Lokalise).

Done! 


Usage

Initialising the framework

We recommend initiate Lokalise iOS framework within - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions

// Subscribe to Lokalise events
[Lokalise sharedObject].delegate = self;

// Set to YES, if you want to use prerelease version of the bundle (see Managing bundles)
[Lokalise sharedObject].preReleaseLocalization = NO;

// Set to YES, to always use locally stored language files (useful for testing)
[Lokalise sharedObject].forceLocalLocalization = NO;

// Enable swizzling
[[Lokalise sharedObject] swizzleMainBundle];

// Update translations to the latest version
[[Lokalise sharedObject] checkForUpdates];


Updating UI

You need to update the interface as soon as Lokalise updates the language bundle. Monitor the following event and update your UI when necessary:

- (void)lokaliseDidUpdateLocalization:(Lokalise*__nonnull)lokalise


Referring keys

No updates are needed to your code with swizzling enabled, refer to the keys as usual:

NSLocalizedString(@"key", @"comment");
NSLocalizedStringFromTable(@"key", @"tableName", @"comment");

If you have not enabled bundle swizzling, you can refer to the keys using Lokalise framework directly:

[[Lokalise sharedObject] localizedStringForKey:@"key" value:@"default value" table:@"table name"];



Managing bundles

Publishing changes

Lokalise supports production and prerelease versions of the bundle and lets you keep different versions of each bundle. Once you generate new bundle via Downloads on Lokalise web dashboard (or using the API call) it goes to the list of bundles that can be found under project settings' Lokalise iOS bundles tab.

Triggering the switches instantly publishes according bundle. 


Testing your localizations

If you are building for TestFlight or Crashlytics and don't want to mess up production app's strings, it's handy to use preReleaseLocalization option.

[Lokalise sharedObject].preReleaseLocalization = YES

Apps compiled with this option enabled, would fetch prerelease version of the bundle.


Adding languages

You need to add language in your Xcode project, only then it becomes available in the app. Lokalise framework does not dynamically add language to the app if you add it in Lokalise.




How did we do