Module Kotlin SDK for Weblate

Weblate is libre software web-based continuous localization system, used by over 2500 libre projects and companies in more than 165 countries.

The Kotlin SDK for Weblate consists of a light-weight Gradle plugin and library for Android projects to support updating localizations without re-building and re-distributing the software binaries.

Requirements

The compiler plugin and library currently requires the following:

• Android Gradle Plugin 9.x
• Android version 11+ (API 30 / R)

Backwards compatibility for older Android versions is planned but may not be possible due to API limitations of the platform itself.

Setup

New versions of the plugins and library are always released together. Ensure you apply both to prevent compatibility issues. Expect breaking changes in alpha and snapshot releases.

1) Installing the Kotlin SDK CDN Add-on

The updated resources are delivered via read-only CDN and thus needs to be installed on the project on the server side. Once installed, the Configuration page will share some required values which needs to be supplied to the plugin in the next step.

You will also need a private API key for the Gradle plugin to publish generated metadata for the Add-on to generate resources to distribute via CDN. You must not share the API key and keep it private.

Check out API documentation for more details.

2) Setting up the Gradle plugin

The plugin is published on the Gradle plugin portal and can be set up using the plugins DSL:

plugins {
    id("org.weblate.android") version "1.0.0-alpha01"
}

The plugin also needs to be configured with the values shared by the Kotlin SDK CDN Add-on. Below is an example for a project hosted on the public instance.

As the plugin needs to access your private API key to publish generated metadata, you can configure it to be read from the build enviornment.

weblate {
    serverUrl = "https://hosted.weblate.org"
    cdnUrl = "https://weblate-cdn.com/c6e2de08693e4fb8bba1ecfae9a8cfd9"
    authToken = "INSERT_TOKEN_HERE" // Replace this value to be read from build environment
    project = "sandbox"
    component = "kotlin-sdk"
}

3) Dependency on the library

The library is published on the maven central repository and can be added to the project like this:

dependencies {
    implementation("org.weblate:android:1.0.0-alpha01")
}

Usage

The first step is to publish the generated metadata after building/finalizing a build. The plugin will generate a metadata file for reach variant and version code everytime the build runs. You can find the generated metadata in build/outputs/weblate/ directory.

1) Publishing the metadata

The plugin will register tasks with the name uploadMetadataForWeblate${variant}. To publish metadata generated with the release build, run the following task:

./gradlew uploadMetadataForWeblateRelease

This step needs to be run everytime there is a new release. You may add the task to be run as a part of your CI/CD environment as the final step.

2) Configuring the library

The easiest way to configure and automate the localization update process would be to configure the Weblate in your app's onCreate method like this:

class WeblateApp : Application() {

    override fun onCreate() {
        super.onCreate()

        // Enables daily localization updates
        Weblate(this)
            .scheduleDailyLocalizationUpdate()
    }
}

In case you wish to handle the update process manually, there are other methods in the Weblate class that may help. We recommend looking at the API documentation for more details.

FAQ

Why my translation updates have a mismatch?

Unless built reproducibly, the resource identifiers generated by Android change. As such, it is recommended to only publish the metadata once the final build has finished and the binaries won't be regenerated to avoid mismatch.

How can I keep my API key private?

You only need the API key to publish the metadata once release build is generated. It's not needed for any other tasks. You can read it from the enviornment and fallback to dummy key if not found.

How to publish metadata when distrubuting the app on F-Droid?

We highly recommend to enable reproducible builds. This will avoid mismatches between resource identifiers generated on building the binaries between them and you (the developer). This way you can keep your API key private too.

There are some guides on F-Droid and IzzyOnDroid for starters.

Can you support Kotlin/Compose Multiplatform?

There is CMP-4197 open for API support. Other areas may be explored which doesn't needs API changes but nothing is planned as of now.

Why not enable binary compatibility validation?

AGP 9.x moved to built-in Kotlin which has broken the binary compatibility validation for Android projects. KT-83410 must be resolved before it can be enabled.

There are some issues on my Android project written in Java. What can I do about it?

Please open an issue with details and expected behavior. The project is written in Kotlin and thus has been mainly tested on Kotlin-only samples. We will be happy to resolve issues, if any, to support Java too.

Funding

NGI Mobifree Fund

This project was funded through the NGI Mobifree Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme under the aegis of DG Communications Networks, Content and Technology. The NGI Mobifree R&D programme is part of Horizon Europe research and innovation programme under grant agreement No. 101135795.