<a id="index-0"></a>

<a id="kotlin-sdk"></a>

# Kotlin SDK for Android

The official Kotlin SDK for Weblate delivers translation updates to Android
applications without rebuilding or redistributing them. Its Gradle plugin
generates and uploads resource metadata for each build. The Android library
downloads updated translations from the public CDNs configured by the
[CDN för Kotlin SDK](https://docs.weblate.org/sv/latest/admin/addons.md#addon-weblate-cdn-kotlin) and [Översättningsfiler-CDN](https://docs.weblate.org/sv/latest/admin/addons.md#addon-weblate-cdn-files) add-ons.
The latter supplies original Android XML translation files.

The SDK is maintained in the [Kotlin SDK repository](https://github.com/WeblateOrg/kotlin-sdk/). The plugin is published on the
[Gradle Plugin Portal](https://plugins.gradle.org/plugin/org.weblate.android)
and the library on [Maven Central](https://central.sonatype.com/artifact/org.weblate/android).

#### WARNING
The SDK is available as an alpha release. Plugin and library versions must
match. Breaking changes can occur before a stable release.

## Requirements

* Weblate 2026.10 or newer with the [CDN för Kotlin SDK](https://docs.weblate.org/sv/latest/admin/addons.md#addon-weblate-cdn-kotlin) add-on.
* Android Gradle Plugin 9.x.
* Android 11 (API 30) or newer for SDK runtime use.

## Configure Weblate

Install Kotlin SDK CDN on the component containing your Android
string resources. For self-hosted Weblate, configure [`LOCALIZE_CDN_URL`](https://docs.weblate.org/sv/latest/admin/config.md#std-setting-LOCALIZE_CDN_URL)
and [`LOCALIZE_CDN_PATH`](https://docs.weblate.org/sv/latest/admin/config.md#std-setting-LOCALIZE_CDN_PATH) first. See [CDN för Kotlin SDK](https://docs.weblate.org/sv/latest/admin/addons.md#addon-weblate-cdn-kotlin) for
public CDN publication, supported resources, and build retention settings.

The installation option Install Translation files CDN is enabled
by default. It installs [Översättningsfiler-CDN](https://docs.weblate.org/sv/latest/admin/addons.md#addon-weblate-cdn-files) to publish the original
Android XML files for the SDK. An existing installation of that add-on is reused.
Both CDNs publish publicly, including translations from private components.

For an existing Kotlin SDK installation without Translation files CDN, use
Install Translation files CDN on the Kotlin SDK add-on configuration
page, or install it from the component’s Add-ons tab. Return to the
Kotlin SDK configuration page afterwards to copy the updated Gradle snippet.

Copy the Gradle configuration from the add-on configuration page. It supplies
the server URL, both CDN URLs, project slug, and component path.
Create a [project-scoped API token](https://docs.weblate.org/sv/latest/admin/access.md#project-api) with permission to edit
the component. Set it as `WEBLATE_API_TOKEN` in the build environment used
to upload metadata. Keep the token out of source control and the application.

## Configure the Android project

In your application module’s `build.gradle.kts`, add the plugin and
library using matching versions:

```kotlin
plugins {
    id("org.weblate.android") version "1.0.0-alpha03"
}

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

Add the configuration copied from Weblate, replacing the example URLs and
slugs below with your component’s values. Read the token from the environment:

```kotlin
weblate {
    serverUrl = "https://hosted.weblate.org"
    project = "my-project"
    component = "android"
    authToken.set(providers.environmentVariable("WEBLATE_API_TOKEN"))

    translationFiles {
        cdnUrl = "https://weblate-cdn.com/TRANSLATION_FILES_ADDON_ID"
    }

    kotlinSdk {
        cdnUrl = "https://weblate-cdn.com/KOTLIN_SDK_ADDON_ID"
    }
}
```

The token is needed only when uploading build metadata. The application
downloads translations from the public CDN without an API token.

## Publish build metadata

Build the application you will distribute, then upload its generated metadata:

```sh
./gradlew uploadMetadataForWeblateRelease
```

The task name depends on the build variant; this example uses `release`.
Metadata is generated under `build/outputs/weblate/`. Upload it for each
application release, for example as the final step in your release pipeline.
Weblate validates uploaded metadata against the [Kotlin SDK build registration](https://docs.weblate.org/sv/latest/contributing/schemas.md#schema-kotlin-sdk-build)
and published manifests against the [Kotlin SDK CDN manifest](https://docs.weblate.org/sv/latest/contributing/schemas.md#schema-kotlin-sdk-manifest).

Resource IDs must match the final distributed binary. Do not rebuild the
application after uploading metadata unless the rebuild produces identical
resource IDs. For independently built distributions such as F-Droid, use
reproducible builds so uploaded metadata matches the distributed application.
See [CDN för Kotlin SDK](https://docs.weblate.org/sv/latest/admin/addons.md#addon-weblate-cdn-kotlin) for build registration and compatibility
with older application versions.

## Enable translation updates

Initialize the SDK in your application’s `onCreate` method:

```kotlin
import android.app.Application
import android.os.Build
import org.weblate.android.Weblate

class WeblateApp : Application() {
    override fun onCreate() {
        super.onCreate()
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
            Weblate(this).scheduleDailyLocalizationUpdate()
        }
    }
}
```

If your application already has an `Application` subclass, add the
initialization there. Otherwise, register `WeblateApp` in your
`AndroidManifest.xml`, using its fully qualified class name:

```xml
<application android:name="com.example.app.WeblateApp">
    <!-- Existing application configuration -->
</application>
```

The SDK schedules daily translation downloads for the current locale on an
unmetered network. The API guard allows applications supporting older Android
versions to keep using bundled translations on those devices.

For manual updates and further usage details, see the [SDK documentation and
sample application](https://github.com/WeblateOrg/kotlin-sdk/).