Group 65Go to Lokalise
All Collections
iOS & Android SDK
Lokalise iOS SDK

Lokalise iOS SDK

Over-the-air localization SDK for iOS. Lightweight and easy to integrate.
Fedya avatar
Written by Fedya
Updated over a week ago

Lokalise iOS SDK

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 SDK 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 SDK requests latest version of the bundle from our servers and if found downloads and stores it locally.

There is additional iOS SDK Live Edit Module, which allows instant preview and updates on the connected device.


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 interface 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 localized using our SDK. 

InfoPlist localization

InfoPlist.string content can't be overridden by our SDK, so don't forget to include the latest translations in your next release.


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

You also need an SDK API token. You can generate it in project settings > General tab.

9555f333cb66ca8888c66ac66553377ccec00e0d

Step 2: Generate the bundle

Go to Downloads page in Lokalise, select "Lokalise iOS SDK" 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 SDK

CocoaPods

To install using CocoaPods simply add these lines to your Podfile:

use_frameworks!
pod 'Lokalise', '~> 0.10.0'


Dependencies will be installed automatically. 

Carthage

To install using Carthage simply add this line to you Cartfile:

binary "https://raw.githubusercontent.com/lokalise/lokalise-ios-framework/master/LokaliseCarthage.json" ~> 0.10.0


Link c++ (libc++.tbd) and z (libz.tbd) libraries to your targets.

Manual

If you would like to install manually, download Lokalise.framework and add it to your project (embed and link).

Link c++ (libc++.tbd) and z (libz.tbd) libraries.

Add Run Script to your Builds Phases.

bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Lokalise.framework/strip-frameworks.sh"


Usage

Configuring the SDK

We recommend configuring Lokalise iOS SDK within - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions app delegate method.

// Provide SDK Token and Project ID and enable Swizzling

[[Lokalise sharedObject] setProjectID:@"Project ID" token:@"SDK Token"];
[[Lokalise sharedObject] swizzleMainBundle];

Lokalise.shared.setProjectID("Project ID", token:"SDK Token")
Lokalise.shared.swizzleMainBundle()

Checking for updates

To get new translations you need to call checkForUpdateWithCompletion: method. A good place for that is in applicationDidBecomeActive: method of your app delegate. It will be called every time application is launched or restored from background.

- (void)applicationDidBecomeActive:(UIApplication *)application {
    [[Lokalise sharedObject] checkForUpdatesWithCompletion:^(BOOL updated, NSError * _Nullable error) {
        NSLog(@"Updated %d\nError: %@", updated, error);
    }];
}

func applicationDidBecomeActive(_ application: UIApplication) {
    Lokalise.shared.checkForUpdates { (updated, errorOrNil) in
        print("Updated: \(updated)\nError: \(errorOrNil)")
    }
}

Updating UI

Lokalise posts LokaliseDidUpdateLocalizationNotification when localization or localizationType is updated. Subscribe to it in any view controller or model to react and update your UI.

- (void)viewDidLoad {
    [super viewDidLoad];
    [NSNotificationCenter.defaultCenter
        addObserver:self
        selector:@selector(updateUserInterface)
        name:LokaliseDidUpdateLocalizationNotification
        object:nil
    ];
}
- (void)updateUserInterface {
    // Update your interface
}    

override func viewDidLoad() {
    super.viewDidLoad()
    NotificationCenter.default.addObserver(
        self, 
        selector: #selector(updateUserInterface), 
        name: NSNotification.Name.LokaliseDidUpdateLocalization, 
        object: nil
    )
}

func updateUserInterface() {
    // Update your interface in Swift
}

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

NSLocalizedString("key", comment: "comment")
NSLocalizedString("key", tableName: "tableName", comment: "comment")

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

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

Lokalise.shared.localizedString(forKey: "key", value: "default value", table: "tableName")

Table name is actually your .strings (or .stringsdict) filename without the extension. Localizable is used by default.


Managing bundles

Publishing changes

Lokalise supports production and prerelease versions of the bundle and lets you keep different versions of each bundle. 

As the bundle is generated, it would take you to project settings / Lokalise iOS SDK section. Flip the according switch in front of the bundle to publish it to production or prerelease (see Testing your localizations section below for description).

Hit Save changes to apply.

Bundle freeze

Lokalise offers you to freeze a particular bundle on a particular app version. As you can see on the print-screen below the "Test_01" bundle is assigned to the apps with build from 0 to 6 and the newest bundle is assigned to the apps with build from 7 to 12. This feature is supported with the Lokalise iOS SDK 0.8.0 and up.

Testing your localizations

If you are building for TestFlight or Crashlytics and don't want to mess up production app's strings, want to see local translation or no translation at all, it's handy to use localizationType option. If it's LokaliseLocalizationPrerelease, the SDK would download fresh Prerelease bundle (according to the table on image above).

// Loads production localization (Default type).
[Lokalise sharedObject].localizationType = LokaliseLocalizationRelease;
Lokalise.shared.localizationType = .release
// Loads prerelease localization.
[Lokalise sharedObject].localizationType = LokaliseLocalizationPrerelease;
Lokalise.shared.localizationType = .prerelease
// Uses localization included in local app bundle.
[Lokalise sharedObject].localizationType = LokaliseLocalizationLocal;
Lokalise.shared.localizationType = .local
// Returns keys instead of localized string.
[Lokalise sharedObject].localizationType = LokaliseLocalizationDebug;
Lokalise.shared.localizationType = .debug

Adding languages

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

Available methods in Swift

You can view all available methods by importing the framework (import Lokalise ) and jumping to its definition (Command + Control click on import Lokalise ).

You will be provided with SDK headers compiled for Swift with comments describing those methods.


Compliance with AppStore review guidelines

Lokalise iOS SDK is compliant with Software Requirements defined in App Store Review Guidelines. Lokalise doesn't load executable code prohibited by rule 2.5.2.


Mobile SDK insights

We provide comprehensive usage stats at project's Statistics page. The reports include:

  • Daily unique users (range)
  • Daily requests (range)
  • App languages (all time)
  • Device languages (all time)
  • Device - App language pairs (all time)
  • App languages (weekly comparison)
  • Monthly active users

Troubleshooting

If you encounter crash that recursively calls these methods

[NSBundle(Lokalise) lokalise_localizedStringsForKey:value:table:]
[Lokalise localizedStringForKey:value:table:]

Ensure that your Localizable.strings and other .strings files are localized as default language of your project and not Base language. 

If this doesn't help or you are experiencing other issues contacts us in live support chat that you can find in bottom right corner of this page.

Did this answer your question?