Get started with the Lingohub Android SDK - How to localize your Android Apps with Over The Air updates

This article shows you how to localize an Android app and make it available in multiple languages by using the Lingohub Android SDK. We will guide you through the process of adding the SDK and making your Mobile app ready to get text/translation updates without releasing a new version (Over The Air updates). With the Android SDK from Lingohub, we help you localize your Android apps efficiently.

Prerequisites

For the purpose of this tutorial, we are creating a new Android project called Funtastic. We are using Android Studio to create this project, but you can use any other IDE (like Eclipse for instance). Funtastic will have English as a source language and will be translated into German.

We created a simple splash screen for the app, including some labels and buttons. The strings that are used in the layout are defined in the strings.xml file:

<resources>
  <string name="claim">Unleash your iamgination</string>
  <string name="login">Login</string>
  <string name="sign_up">Sign Up</string>
  <string name="forgot_password">Forgot your password?</string>
</resources>

Now let's assume we have finished our app project and published it to the Google Play Store (Yeah!). But shortly after the release we notice a typo in our strings file. Instead of imagination we typed iamgination. Of course, such a typo is embarrassing, so we want to quickly fix it. Without the Lingohub SDK, our only option would be to create a new release, which is quite cumbersome and slow. This is where the magic of the Lingohub SDK comes in handy.

Integrating the SDK

The Lingohub SDK is hosted on jitpack, so before you add the SDK to your gradle file, you have to add the jitpack maven repository:

allprojects {
    repositories {
        ...
        maven {
            url 'https://jitpack.io'
        }
    }
}

Now, add the Lingohub SDK dependency to your application-level .gradle file:

dependencies {
    ...
    implementation 'com.lingohub:lh-android-sdk:1.0.0-beta01'
}

Voila, now you have added the Lingohub SDK as a dependency to your project. That means you can now use the Lingohub classes in your code. However, before we do that, we have to configure Lingohub to get the API Key and the Project Id.

Connecting to Lingohub

Before you start with this section, make sure you have either an iOS or Android project on Lingohub. How you can create one, is in detail described in our help. To connect the SDK to Lingohub, two steps are necessary:

1. Creating a package that contains the resource files
2. Creating an API on Lingohub for the project

Creating a package

Creating a package is really simple and can be done through Lingohub's intuitive UI. By creating a package you have to enter the following information:

• Platform: Either iOS or Android. This option tells the system what kind of files (.string or .xml) the package will contain. Note, although Lingohub's projects are associated with only one platform, it is possible to create an Android package in an iOS project and vice versa. So if you have one project for both, Android and iOS, you need to create two packages for OTA updates.
• Stage: This is optional to use. Basically it allows you to distinguish between two environments, production and pre-production, so you can test the new texts before releasing it to production.
• Version from and to: Since you normally don't have one version out in the wild, it is handy to specify for which versions a package is responsible. This allows you to manage different and incompatible versions. The from version is inclusive and the to version is exclusive, as it is in most programming languages.

A package consists of one or more releases. You can think of a release like a version of a package. Only one release can be active. Check the following graphic on how the SDK determines which package-release combo to use. Note: We created a package that is responsible for all Android apps, which means the texts stay compatible between the versions. The actual version of your app will be used against the package version.

For this tutorial, we will use

• Platform: Android
• Stage: Production
• Version from: 1
• Version to: 3

Lingohub will automatically create a release for a new package.

Creating an API Key

Now you need to add an API Key and the Project Id to your project, so that the SDK can access the Lingohub API. Creating the API is really easy, simply click the Create API Key under packages. Then a dialog shows up showing the new API Key + the Project Id. Important, the API key is not displayed again, you can only generate a new one, so please make sure that you save your API Key + Project Id somewhere safe!

Having now the necessary information, we need to set it in the SDK:

class App : Application() {

    override fun onCreate() {
        super.onCreate()

        Lingohub.configure(this, "<api key>", "<project id>")

        // Add following line only if you want to use pre-production packages.
        Lingohub.setPreproductionEnabled()

        // Fetch the latest translations from Lingohub
        Lingohub.fetchStrings()
}

Replacing the texts

In order to be able to replace strings, the SDK needs to be wrapped around your activity context. In your activity override the attachBaseContext() as follows:

// we use a base class for all our activities
abstract class BaseActivity : AppCompatActivity() {
    override fun attachBaseContext(newBase: Context) {
        super.attachBaseContext(Lingohub.wrap(newBase))
    }
    override fun getResources(): Resources {
        return Lingohub.wrap(baseContext).resources
    }
}

That's it! Every time your app starts, Lingohub checks for updated strings and replaces them whenever a string is requested by your app.

Over The Air updates

Now everything is in place and the SDK listens to changes on Lingohub. So the next step is to inform the SDK when we want the texts updated. We can do this by creating a new release for the package that we created.

Important: As stated above a package can have multiple releases, but only one can be active. The active release will be delivered to the SDK. This way you have the ability to version your releases and if necessary quickly switch back. The SDK then will ping the Lingohub API and will be informed that new texts are available. So it will download and update the texts. This only happens once, the texts are then stored in your app.

And like magic all your users get the new texts without the need for a new release:

Summary

We hope we got you as excited as we are about this new feature. Check out the code of this tutorial and the SDK. If you have any feedback or questions, don't hesitate to contact us. We happily help you setting up OTA updates for your awesome app.

Btw. if you are not a Lingohub user yet, start the free trial and contact us!

Links:

• Lingohub Android SDK
• Funtastic project