Lokalise Android SDK

Updated 7 days ago ​by Arthur

Introduction

This guide assumes that you have already prepared your Android app for localization as SDK is designed to work with Android resources.

Lokalise Android SDK is available as an .aar library (can be downloaded here) or as a Maven dependency (please check out Step 3 in the Getting Started section) and can be easily included in your projects. Once the translations are finalized in Lokalise editor, you generate a bundle using Lokalise Download page. 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.


Reporting issues

Please use this issue tracker or contact Lokalise support to report any issues you may encounter.


Limitations

Some views are not supported when inflating from XML (Action bar, Menu items, Android preferences, may be others), but you can still get the latest translations via getString(), getText(), getQuantityString() and other system methods, and set the content of these views programmatically.


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 Android 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 the latest strings in your project when releasing the app.


Step 3: Include Lokalise SDK in your project

First you need to add https://maven.lokalise.co to your repository list and include aur library as well as google GSON library in your .gradle file:

repositories {
    ...
    maven {
        url "https://maven.lokalise.co"
    }
}
...
dependencies {
    ...
    compile 'com.lokalise.android:ota-sdk:1.+'
    compile 'com.google.code.gson:gson:2.8.0'
}

If you are using ProGuard, add the following rules:

-keep class co.lokalise.android.sdk.** { *; }
-dontwarn co.lokalise.android.sdk.*


Step 4: Initialise the SDK

For this step you will need your API token (generate read-only token in your personal profile page) and the Project ID of the desired project (obtained in the project settings). In you main Application class include the following code:

public class MyApplication extends Application {
    ...
    @Override
    public void onCreate() {
        super.onCreate();
        // Initialise Lokalise SDK with your personal API token and project id
        // It is important to call this right after the "super.onCreate()"
        // If you are using AppCompatDelegate.setCompatVectorFromResourcesEnabled(true)
        // make sure it is called before LokaliseSDK.init()
        LokaliseSDK.init("<api token>", "<project id>", this);
    
        // Add this only if you want to use pre-release bundles
        LokaliseSDK.setPreRelease(true);
        
        // Fetch the latest translations from Lokalise (can be called anywhere)
        LokaliseSDK.updateTranslations();
    }
    ...
}

We will need to inject Lokalise SDK into the Activity context as well. To do so, we recommend you create a base Activity class and extend all your activities from it. Add the following code into your activity:

public class MainActivity extends AppCompatActivity {
    ...
    @Override
    protected void attachBaseContext(Context newBase) {
        // Inject the Lokalise SDK into the activity context
        super.attachBaseContext(LokaliseContextWrapper.wrap(newBase));
    }
    ...
}

If you are using Calligraphy library for Android, attaching to context should look like this:

...
super.attachBaseContext(LokaliseContextWrapper.wrap(
    CalligraphyContextWrapper.wrap(newBase)
));
...

That's it! You are ready to go!


Usage

Updating translations

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

...
<TextView
    android:id="@+id/test"
    android:text="@string/hello_world"
    ... />
...

Or from code:

TextView test = (TextView) findViewById(R.id.test);
test.setText(R.string.hello_world);

If you want your Action bar to have the latest translations, set it's title programmatically:

@Override
protected void onResume() {
    super.onResume();
    setTitle(R.string.hello_world);
}

Changing application locale

To change the locale of your application, use the LokaliseSDK.setLocale(<Language ISO e.g. "en">, <Region ISO e.g. "GB">) method. 

There is no need for custom locale changing code or context wrappers, simply call this method and restart the Activity.

Dynamically adding keys

Sometimes you need to add new strings without recompiling the application. 

After adding a new key via the Lokalise interface and creating a new Android SDK bundle, you can refer to the new key by name using the following code:

...
LokaliseResources resources = new LokaliseResources(context);
String newKey = resources.getString("new_key_name");
if(newKey != null) {
    // do something with the new value
}

Please note that there is no guarantee that the key will exist when you request it, since you can pass any key name to the method, so make sure t o check whether the returned value is null.

Callbacks (available in version 1.3.0)

If you need to know when Lokalise is done downloading a new translation bundle, there are several options.

Lokalise callback

The simplest way is to use the LokaliseCallback interface:

LokaliseCallback myCallback = new LokaliseCallback() {
    @Override
    public void onTranslationsUpdated(long oldBundleVersion, long newBundleVersion) {
        // Do something
    }
};
LokaliseSDK.addCallback(myCallback);

If you need to remove a callback, simply use LokaliseSDK.removeCallback(myCallback);

Broadcast receiver

You can also receive notifications about bundle updates via Broadcast receiver:

...
IntentFilter myIntentFilter = new IntentFilter(LokaliseDefines.INTENT_TRANSLATIONS_UPDATED);
BroadcastReceiver myReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        long previous_version = intent.getLongExtra(LokaliseDefines.EXTRA_BUNDLE_VERSION_OLD, 0);
        long current_version = intent.getLongExtra(LokaliseDefines.EXTRA_BUNDLE_VERSION_NEW, 0);
        // Do something
    }
};
@Override
protected void onResume() {
    super.onResume();
    registerReceiver(myReceiver, myIntentFilter);
}
@Override
protected void onPause() {
    super.onPause();
    unregisterReceiver(myReceiver);
}
...


Managing bundles

Publishing changes

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

    After you make changes in Lokalise editor, navigate to Downloads section in the project and select Lokalise Android SDK as the format.
Lokalise Android SDK bundle generation


As the bundle is generated, it would take you to project settings / Lokalise Android SDK section. Flip the according switch in front of the bundle to publish it to production or prerelease.

Triggering the switches instantly publishes according bundle. 


Adding languages

Although if you add a new language to the bundle, it will be available in the application, we advise to release a fresh build with natively included resources for the new language since it may cause inconsistent translation of the interface (for example Action bar or application name will not be translated).


How did we do