Introduction

Lokalise iOS SDK Live Edit Module is the brand-new extension of Lokalise iOS SDK. The Module shows the constantly updated mobile screen in your Lokalise editor. The screen mirrors the linked device with installed prerelease version of your app. First, it provides an editor or a QA / LQA specialist with the live full context of the translated string. Second, it ensures the pixel-perfect visual experience, showing the edited strings in proper font, proper place, just as the end users will see it.

How it works? See 1 minute video.

Demo app

Want to try how it works? We've built a Lokalise Companion app that would create a demo project for you and let you play with the Live Edit Module.


Prerequisities

Before using Live Edit Module you need to make sure the following is done:

  1. Your app is prepared for localization
  2. Lokalise iOS SDK has already been integrated

Features

Live Mode

  • Navigate the app on the device
  • The correspondent strings will be shown in the Editor
  • See the translation updates on the device instantly
  • Change the current app locale in the Editor
  • Make screenshots live (coming soon)

Debug menu for Lokalise

  • Shake the device to activate
  • Check for updates
  • Change the Localization Type (Release, Prerelease, Local, Debug) 
  • Change the application locale (affecting only the current session)
  • Stay aware of the current bundle version

Setting up

Keys and UI updates

There are two steps required in order to add Live Edit Module to your app:

  1. Provide the SDK with the keys associated with each view controller
  2. Update the app UI in response to the update event

System localization

Some of the system interface objects, e.g. search bar, might not get translated  when changing the application language at runtime.

Requirements

  • Xcode 9.1+
  • Lokalise SDK >= 0.8.1
  • iOS 8.0+

Installation

In order to install using CocoaPods simply add this line to your Podfile:

use_frameworks!
pod 'LokaliseLiveEdit', '~> 0.2.5'

Dependencies will be installed automatically.  If you would like to install manually, download LokaliseLiveEdit.framework and add it to your project. You will also need to install the Lokalise SDK.

Integrating into your app

Setup

// Configure Lokalise SDK first in AppDelegate.application(didFinishLaunchingWithOptions:)
Lokalise.shared.setAPIToken("<API TOKEN>", projectID: "<PROJECT ID>")
Lokalise.shared.swizzleMainBundle()
// Without this call LokaliseLiveEdit uses isolated Lokalise framework instance.
LokaliseLiveEdit.shared.use(lokaliseFramework: Lokalise.shared)

You can find more details on Lokalise SDK here.

Presenting the Debug menu

// This will enable the shake gesture support. Debug menu will appear once you shake your device.
LokaliseLiveEdit.shared.isShakeGestureEnabled = true
// If another library in your app is using the shake gesture you can present the debug menu manually instead.
LokaliseLiveEdit.shared.presentDebugViewController()

Providing keys

Since version 0.1.5 Live Edit Module automatically extracts keys associated with translations in your current View Controller. Exact matches, concatenated translations, and translations with placeholders are supported.

If the keys you expect to appear are still not detected by Live Edit Module, implement the LokaliseKeysProvider protocol on your View Controllers. Use localizableKeys() method to provide this controller with available keys.

extension RootViewContoller: LokaliseKeysProvider {
    func localizableKeys() -> [String] {
        return [
            "welcome_title",
            "welcome_description",
            "welcome_button_continue"
        ]
    }
}

Custom UI

Additional setup is required if your custom UI elements do not use UILabel, UIButton, UITextView, UITextfield or you are using a 3rd party UI library that doesn't.

To do that you need to implement the LokaliseStringExtractable  protocol. The extractString  method should provide text that is currently displayed.

extension CustomUIElement: UIView {
    public func extractString() -> String? {
        return text
    }
}

Here you can find a ready-to-use extension for AsyncDisplayKit (we will be adding more to this list). If you are using a library that doesn't work out-of-the-box with Lokalise Live Edit contact our support, we will look into and try to add it our list.

Updating UI

Once the translation is updated in the Lokalise editor, our framework posts  the LokaliseDidUpdateLocalizationnotification. You should subscribe to it, then call your update UI method which will re-render the UI of the view controller.

extension RootViewController {
    func subscribe() {
        NotificationCenter.default.addObserver(self, selector: #selector(updateUI), name: NSNotification.Name.LokaliseDidUpdateLocalization, object: nil)
    }
    func updateUI() {
        titleLabel.text = NSLocalizedString("welcome_title", "")
        descriptionLabel.text = NSLocalizedString("welcome_description", "")
        button.setTitle(NSLocalizedString("welcome_title", ""), for: .normal)
    }
}

Using the Live Edit Module

Step 1

Open the Live Edit Module page in the Lokalise editor by clicking the Live Edit icon in the toolbar.

Step 2

Shake your phone to open the Live Edit Module menu. In case other libraries in your app are using the shake gesture, you need to override the default setting and open the debug menu manually).

Step 3

Flip the Live Mode switch to scan the QR code. On the device you will be prompted to scan the session QR code . You also have an option to enter it manually (if you use a simulator it is the only option).

The Live Mode is turned off by simply flipping the Live Mode switch.

Troubleshooting

Consult Lokalise SDK Troubleshooting section.

Did this answer your question?