Module Kotlin SDK for Weblate

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

Part of Weblate — a privacy-respecting localization platform built on open-source foundations.

Requirements

The compiler plugin and library currently require 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 the add-on needs to be installed on the project on the server side. Once installed, the Configuration page will share some required values that need 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 environment.

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 environment 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.

Releases

The plugin and library share the version in gradle/libs.versions.toml. Push a tag with that exact version to publish both packages and create a GitHub release with generated notes. Manual runs of the Publish release workflow must select an existing tag; branch runs and tags that do not match the version fail before publishing. Versions with prerelease suffixes, such as 1.0.0-alpha01, are marked as prereleases.

GitHub releases include the Android library AAR, Gradle plugin JAR, and their source and documentation JARs. These are the files built by the package publishing jobs, with versioned filenames. Each job builds, collects, attests, and uploads its artifacts before publishing its package. The GitHub release waits for both package publishing jobs to succeed.

Release immutability must be enabled under Settings → General → Releases → Enable release immutability. All assets are uploaded to a draft before publication locks the assets and tag. An interrupted upload leaves a draft that can be completed by rerunning the GitHub release job. Published releases are left unchanged on retries; correcting their assets requires a new version. Artifact preparation failures are safe to retry because package publication has not started. Once both packages have published successfully, retry only the GitHub release job to avoid republishing an existing package version. If a publication step fails, check whether the registry accepted the package before retrying that job.

Build provenance complements the library's Maven PGP signatures. To verify a downloaded file's build provenance, use the GitHub CLI:

gh attestation verify android-1.0.0-alpha01.aar --repo WeblateOrg/kotlin-sdk

Immutable releases also have a release attestation linking the tag, commit, and assets. Verify the release and a downloaded asset with:

gh release verify 1.0.0-alpha01 --repo WeblateOrg/kotlin-sdk
gh release verify-asset 1.0.0-alpha01 android-1.0.0-alpha01.aar --repo WeblateOrg/kotlin-sdk

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.