Lokalise Android SDK

Updated a month ago ​by Arthur

Disclaimer

Current version of Android SDK is beta. We do not recommend releasing it to production yet.


Reporting issues

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


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 currently available as an .aar library (can be downloaded here) 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.


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

Copy the lokalise-sdk.aar (can be downloaded here) file into you libs folder and include the following lines into your .gradle file:

repositories {
    ...
    flatDir {
        dirs 'libs'
    }
}
...
dependencies {
    ...
    compile(name:'lokalise-sdk', ext:'aar')
    compile 'com.google.code.gson:gson:2.8.0'
}


Step 4: Initialise the SDK

For this step you will need your API token (obtained in your account settings) 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()"
        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();
    }
    @Override
    protected void attachBaseContext(Context base) {
        // Inject the Lokalise SDK into the application context
        super.attachBaseContext(LokaliseContextWrapper.wrap(base));
    }
    ...
}

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

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


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. 


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