Introducing Lokalise-Loader, an Android Library by Orangesoft

As you probably know, Lokalise provides an Android SDK featuring over-the-air localization for mobile apps. While working on localizing the Stream Vision 2 mobile app, Orangesoft, one of our customers, has recently introduced Lokalise-Loader, a Kotlin library providing an easy way of pulling Android string resources from Lokalise. In this article, we’ll provide an overview of this solution.

You might also be interested in learning how to translate Android apps with Lokalise and how to perform Kotlin internationalization.

What’s the challenge?

The Android SDK enables you to generate archives with up-to-date translation data, use them when building the app, and then serve it to the end users. All in all, this process is quick and simple. However, there’s one caveat: you have to repeat this on a regular basis, and if you are adding new translation strings often, it might become a chore.

Another requirement for the Stream Vision 2 app was the ability to use it to the full extent in offline mode. By default, every time a user opens a mobile app, Android will try to load the app’s resources based on the system language set on the user’s device. But in this exact case, the app has to be localized by default to support offline usage. Unfortunately, there were no existing solutions available on the net; therefore, Orangesoft decided to create their own custom library, allowing users to update resources with a single click. So, they came up with the Lokalise-Loader library which provides an easy way of pulling Android translations from Lokalise.

So, does it work?

The overall idea is quite simple: Lokalise-Loader sends an API request, creates XML translation files, and places them in the project’s folder.

Here’s a step-by-step process:

1. Fetch a list of all available project languages using the Languages endpoint.
2. Fetch all translation keys using the Keys endpoint.
3. Get all the translations for each language using the Translations endpoint.
4. Create an XML file for each locale.
5. Update the existing files in the project directory.

That’s it! You can find the library’s source code and documentation on GitHub.

How do you use it?

First of all, add the Maven repository to your Gradle file:

repositories {
    maven { url = uri("https://jitpack.io/") }
}

Next, add the library definition to the dependencies:

implementation("com.github.Orangesoft-Development:lokalise-loader:<version>")

The Lokalise-Loader library provides a Gradle task to load translations during builds. In order to use this task, you’ll need to register it in the following way:

task<LokaliseUpdateTask>("lokalise-update") {
    targetDir = "<resources-directory-path>"
    apiToken = "<lokalise-user-api-key>"
    projectId = "<lokalise-projectId>"
    platforms = listOf(data.Platforms.Android)
}

Alternatively, you can call the create method directly on LokaliseLoader, like this:

val lokaliseLoader = LokaliseLoader.create {
    apiToken = "<lokalise-user-api-key>"
    projectId = "<lokalise-projectId>"
    outputDirPath = "<resources-directory-path>"
    platforms = listOf(data.Platforms.Android)
}
lokaliseLoader.load()

On top of that, it’s possible to specify a list of keys to download from Lokalise. This allows you to manage specific translation keys more efficiently, especially for modular projects. This might come in handy if you would like to upload certain translations to a non-main module and prevent those resources from being duplicated in the main module. To achieve this, use the following approach:

task<LokaliseUpdateTask>("lokalise-update") {
    targetDir = "<resources-directory-path>"
    apiToken = "<lokalise-user-api-key>"
    projectId = "<lokalise-projectId>"
    platforms = listOf(data.Platforms.Android)
    keys = listOf(
        "my_first_string",
        "my_second_string",
    )
}

Conclusion

In Stream Vision 2, the Gradle task is used in CI/CD before the release. It automatically updates the strings to the current version. This way, users without Internet access will have the newest translations while using the application. So, as you can see, Lokalise-Loader is a neat and handy library that can make your life as a developer even simpler.

That’s it for today, folks! Thank you for staying with me, and until next time.