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.
For usage instructions, please see the official documentation website.
API key is needed so that the plugin can POST your app's generated metadata containing resource identifiers
and string keys to the server to generate resource table (.arsc file) to overlay during app's runtime.
The app can either use the org.weblate:android library provided by this project or interact with the
REST APIs manually. The updated translations will be packaged into a resource table (.arsc file) and
served via public read-only CDN.
Since Android 11, there is ResourcesLoader API that allows overriding/overlaying resources during app's runtime. The library uses this API to load updated translations.
Unless built reproducibly, the resource identifiers generated by Android change even for the same commit. 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.
You only need the API key to interact with tasks provided by Gradle plugin. It is never bundled with-in the app. You can read it from the environment and fallback to dummy key if not found.
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 and publish the generated metadata by yourself.
There are some guides on F-Droid and IzzyOnDroid for starters.
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.
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.
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.
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-sdkImmutable 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-sdkThis 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.