tech · Clock4 min · 10 Jan 2022

How We Created Lokalise-Loader, an Android Library for Faster App Localization

Dmitry Kuzmich

Dmitry Kuzmich

Android Developer

lokalize-loader
Illustration by Amir Kerr

The Orangesoft team has released several applications for international markets. Stream Vision 2 is one of our top projects worldwide. It is a mobile and web app for hunters, researchers, and search and rescue professionals that allows users to stream video from Pulsar and Yukon electro-optic devices to their smartphones and to control the equipment remotely. 

As Yukon Advanced Optics Worldwide, the owner of Stream Vision 2, is recognized as the largest developer of optical observation devices and has customers all over the world, its app must work smoothly in various regions. Thus, it supports 27 languages. Multi-language support not only improves user experience but also simplifies work with thermal imaging and digital night vision units.

Here's how we approached localizing the Stream Vision 2 Android app using the Lokalise platform and the library we created to make the localization process even smoother.

But first, let's talk about the notions of localization and translation management systems (TMSs).

What are App Localization and Translation Management Systems?

App localization is the process of adapting an app to appeal to different geographic target markets.

Localization goes beyond mere translation and linguistic differences: it is about cultural characteristics. For example, certain symbols, images, or phrases may be innocuous in the US but could be very offensive in another country.

Imagine that your application supports 27 locales like Stream Vision 2 does. This means that you have 27 files with the strings used in the application’s user interface. These may include screen names in the toolbar, text on buttons, and message text in the pop-ups. Each file is in XML format and includes all of the strings in your application so that they can be easily translated into another language. For a developer to use any string in the application code, it must be present in every localization file. 

If you create a small application for a specific region, localization usually doesn’t take much time. But as the number of supported locales increases, the localization process becomes a real challenge. Since it is a manual process, it takes hours of copying and pasting, depending on how many changes you need to make. What's more, all this monotonous work will probably lead to mistakes.

A translation management system would be of great use to automate routine operations. TMS is software designed to support managing the localization and translation process. It helps organize the localization workflow, track the progress of translation projects, and reduce manual tasks via automation. 

How to Choose a Translation Management System?

Today, the market offers different TMSs, and we chose the best suited to our specific use case. We needed to find localization management software that would help us reduce manual tasks via automation and ensure optimal processes. Lokalise fit into our tech stack, existing workflows, and current technical reality so we could make localization projects unfold easily.

Lokalise has at least two undeniable benefits: the availability of SDKs for Android and iOS and cloud storage of all locales with access through an easy-to-use admin panel. The SDK automatically connects to the locale storage and replaces the embedded string resources with those listed in the administrative panel.

What Was the Challenge?

With Lokalise, you can generate archives with up-to-date resources and then use them when building the app for release. But the problem is that you have to repeat this task every time a new string appears. After running this operation several times, the process no longer seems so simple. 

By default, any time a user opens an app, Android will try to load the app’s resources based on the system language set on the user’s device. But since the users of Stream Vision 2 mostly use it in offline mode, we need the app to be localized by default.

Since we didn't find any existing solutions on the web, we decided to create our own utility that allows updating resources with one click. Lokalise-Loader is a Kotlin library providing an easy way of pulling Android string resources from Lokalise.

How Does This Library Work?

Lokalise-loader sends an API request to Lokalise and generates translation files in the project's folder. The process is quite simple:

  1. Getting a list of all locales using the Lokalise API
  2. Getting all string keys using the Lokalise API
  3. Getting all the string resources for each locale
  4. Creating an XML file for each locale
  5. Updating the existing files in the project directory

How Can You Use the Lokalise-Loader in Your Project?

1. Add the maven repository to your Gradle file:

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

2. Add the library definition to the dependencies:

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

3. The library provides a Gradle task to load string resources during builds. To use the task, register it like in the sample below:

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

4. Or use LokaliseLoader directly using create method:

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

5. Additionally, you can specify a list of keys to load from Lokalise. This might be helpful if you want to upload some translations to a non-main module and prevent those resources from being duplicated in the main module.

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",
    )
}

In Stream Vision 2, we use Gradle-task in CI/CD before the release. Gradle-task automatically updates the strings to the current version. This way, users who are not connected to the Internet while using the application will have the newest translations.

Now you can easily add new elements to your project or update existing ones to fit your locales. The Lokalise platform, together with Lokalise-Loader, allows you to stay on top of performance and see the direct impact of localization efforts.

Rate this article!

(6 ratings, average: 5 out of 5)

red-title-line
Insights
Latest Articles