Introduction

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

How it works? See 1 minute video.

Demo app

Want to try it and see how it works? We've built a Lokalise Companion app that will 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 the 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 during runtime.

Requirements

  • Xcode 10.2+
  • Lokalise SDK >= 0.9.0
  • iOS 8.0+

Installation

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

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

Dependencies will be installed automatically. If you would like to install manually, download the 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("<SDK 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 the Lokalise SDK here. Note, SDK tokens need to be generated under project settings > General tab.

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

Version 0.1.5 of the Live Edit Module and above automatically extracts the 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 the 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 the AsyncDisplayKit (we will be adding more to this list). If you are using a library that doesn't work directly with the Lokalise Live Edit please contact our support, we will look into and try to add it to our list.

Updating UI

Once the translation is updated in the Lokalise editor, our framework posts the LokaliseDidUpdateLocalization notification. You should subscribe to it, then call up 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 Mobile button in the toolbar under the more options dropdown menu.

Step 2

Shake your phone to open the Live Edit Module menu. If 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

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

Live Mode is turned off by simply deactivating the Live Mode switch.

Troubleshooting

Consult Lokalise SDK Troubleshooting section.

Did this answer your question?