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 Kotlin SDK CDN and Prekladové súbory 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.

Varovanie

SDK je dostupné vo verzii alfa. Verzie zásuvného modulu a knižnice sa musia zhodovať. Pred vydaním stabilnej verzie môže dôjsť k nekompatibilným zmenám.

Požiadavky¶

Weblate 2026.10 or newer with the Kotlin SDK CDN add-on.
Doplnok Android Gradle 9.x.
Android 11 (API 30) alebo novší na použitie v čase behu SDK.

Konfigurácia Weblate¶

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 Prekladové súbory 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.

Konfigurácia projektu Android¶

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")
}

Pridajte konfiguráciu skopírovanú z Weblate a nahraďte nižšie uvedené ukážkové URL adresy a identifikátory vlastnými hodnotami komponentu. Token načítajte z premennej prostredia:

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"
    }
}

Token je potrebný iba pri nahrávaní metadát zostavenia. Aplikácia sťahuje preklady z verejnej CDN bez použitia tokenu API.

Publikovanie metadát zostavenia¶

Zostavte aplikáciu, ktorú budete distribuovať, a potom nahrajte vygenerované metadáta:

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

Povoliť aktualizácie prekladov¶

Inicializujte SDK v metóde onCreate vašej aplikácie:

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>

SDK plánuje každodenné sťahovanie prekladov pre aktuálne miestne nastavenie pri pripojení k nemeranej sieti. Ochranný mechanizmus API umožňuje aplikáciám podporujúcim staršie verzie systému Android naďalej používať v týchto zariadeniach preklady pribalené k aplikácii.

For manual updates and further usage details, see the SDK documentation and sample application.