Android 適用的 Kotlin SDK¶
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 翻譯檔案 CDN add-ons. The latter supplies original Android XML translation files.
此 SDK 的程式碼在 Kotlin SDK 儲存庫 中維護。外掛發佈於 Gradle Plugin Portal,函式庫則發佈於 Maven Central。
警告
此 SDK 目前提供 alpha 版本。外掛與函式庫的版本必須一致。穩定版發佈前,可能出現不相容的變更。
需求¶
Weblate 2026.10 或更新版本,並安裝 Kotlin SDK CDN 附加元件。
Android Gradle Plugin 9.x。
SDK 執行階段須使用 Android 11 (API 30) 或更新版本。
設定 Weblate¶
在包含 Android 字串資源的組件上安裝 Kotlin SDK CDN。自行託管的 Weblate 請先設定 LOCALIZE_CDN_URL 與 LOCALIZE_CDN_PATH。公開發佈至 CDN、支援的資源及建置保留設定,請參閱 Kotlin SDK CDN。
The installation option Install Translation files CDN is enabled by default. It installs 翻譯檔案 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.
設定 Android 專案¶
在應用程式模組的 build.gradle.kts 中,加入版本一致的外掛與函式庫:
plugins {
id("org.weblate.android") version "1.0.0-alpha03"
}
dependencies {
implementation("org.weblate:android:1.0.0-alpha03")
}
加入從 Weblate 複製的設定,將下列範例中的網址與代稱換成您組件的值。從環境變數讀取權杖:
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"
}
}
只有上傳建置中繼資料時需要權杖。應用程式會從公開 CDN 下載譯文,無須 API 權杖。
發佈建置中繼資料¶
建置要散布的應用程式,然後上傳產生的中繼資料:
./gradlew uploadMetadataForWeblateRelease
工作名稱取決於建置變體,此範例使用 release。中繼資料會產生在 build/outputs/weblate/ 下。每次發佈應用程式時都請上傳中繼資料,例如將此動作設為發佈流程的最後一步。Weblate 會依 Kotlin SDK build registration 驗證上傳的中繼資料,並依 Kotlin SDK CDN manifest 驗證已發佈的資訊清單。
資源 ID 必須與最終散布的二進位檔一致。上傳中繼資料後,不要再次建置應用程式,除非再次建置產生的資源 ID 完全相同。對於 F-Droid 等獨立建置的發行版本,請採用可重現建置,確保上傳的中繼資料與散布的應用程式一致。建置註冊及與舊版應用程式的相容性,請參閱 Kotlin SDK CDN。
啟用翻譯更新¶
在應用程式的 onCreate 方法中初始化 SDK:
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()
}
}
}
若應用程式已有 Application 子類別,請在該子類別中加入初始化程式碼。否則,請在 AndroidManifest.xml 中使用完整限定類別名稱註冊 WeblateApp:
<application android:name="com.example.app.WeblateApp">
<!-- Existing application configuration -->
</application>
SDK 會排程每天在不按流量計費的網路上,下載目前語系的譯文。API 版本防護條件讓支援舊版 Android 的應用程式,在這些裝置上仍可繼續使用內附譯文。
手動更新與進一步的用法,請參閱 SDK 文件與範例應用程式。