Kotlin-SDK für 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 Kotlin-SDK-CDN and Übersetzungsdateien-CDN add-ons. The latter supplies original Android XML translation files.

The SDK is maintained in the Kotlin SDK repository. The plugin is published on the Gradle Plugin Portal and the library on Maven Central.

Warnung

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

Anforderungen

  • Weblate 2026.10 oder neuer mit der Kotlin-SDK-CDN-Erweiterung.

  • Android-Gradle-Plugin 9.x.

  • Android 11 (API 30) oder neuer für die Nutzung der SDK-Laufzeitumgebung.

Weblate konfigurieren

Install Kotlin SDK CDN on the component containing your Android string resources. For self-hosted Weblate, configure LOCALIZE_CDN_URL and LOCALIZE_CDN_PATH first. See Kotlin-SDK-CDN for public CDN publication, supported resources, and build retention settings.

The installation option Install Translation files CDN is enabled by default. It installs Übersetzungsdateien-CDN 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 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.

Das Android-Projekt konfigurieren

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

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:

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:

./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 and published manifests against the Kotlin SDK CDN 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 Kotlin-SDK-CDN for build registration and compatibility with older application versions.

Übersetzungsaktualisierungen aktivieren

Initialize the SDK in your application’s onCreate method:

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:

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