Messagevisor

SDKs

Android SDK

Native Android applications can use the Java SDK from Kotlin or Java to evaluate translations, message overrides and locale formatting on the device.

There is no separate Android package. This guide covers Android integration, while the Java SDK reference describes the complete API. For React Native applications, use the React Native guide.

Installation

Add the SDK and ICU module to your app module:

app/build.gradle.kts
dependencies {
    implementation("com.messagevisor:messagevisor-sdk:0.3.0")
    implementation("com.messagevisor:messagevisor-module-icu:0.3.0")
}

These artifacts are hosted on GitHub Packages. Add the repository to your Gradle dependency resolution configuration and provide build credentials as described in Java installation. Keep credentials outside source control and never bundle them in the Android application. They are needed to download the SDK at build time, not to evaluate translations on a device.

The example application uses Java 17 compilation and core library desugaring for APIs such as java.time on older Android devices:

app/build.gradle.kts
android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
}

The example targets Android API 23 or newer. Align the Android Gradle Plugin, Kotlin compiler and desugaring configuration with your application's build setup.

Load a datafile

The SDK evaluates a generated datafile; it does not download one for you. Bundle a starter file in app assets, fetch it from your deployment, or combine both approaches for offline startup.

The example application fetches this public demonstration datafile:

https://messagevisor-example-cloudflare-pages.pages.dev/production/messagevisor-mobile-en-US.json

Use your own deployment for production content. For network access, declare the internet permission outside the application element in AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

Perform network and file operations away from the main thread. Check HTTP status, set timeouts and keep a last known working datafile if refresh fails. The example uses HttpURLConnection on an executor and returns results to the UI thread.

Create an instance and translate

Once your loader has returned the JSON text, create an instance:

import com.messagevisor.modules.icu.IcuModule
import com.messagevisor.sdk.Messagevisor
import com.messagevisor.sdk.MessagevisorOptions
fun createMessages(datafileJson: String): Messagevisor = Messagevisor.create(
    MessagevisorOptions.builder()
        .datafile(datafileJson)
        .timeZone("America/New_York")
        .addModule(IcuModule.create())
        .build(),
)

With the returned instance named m, evaluate plain copy and ICU messages:

val signIn = m.translate("auth.signin")
val contact = m.translate(
    "nav.contact",
    mapOf("closingTime" to java.time.Instant.parse("2026-08-02T21:30:00Z")),
)

Assign the returned strings to your views on the UI thread. For Compose, expose them through observable application state; the Java SDK does not provide a Compose provider or automatically trigger recomposition.

Updates and lifecycle

  • Load the selected locale's datafile before calling m.setLocale(locale). Loading another locale does not automatically select it.
  • m.setDatafile(datafileJson) merges data for that locale. Use m.setDatafile(datafileJson, true) when replacing a complete snapshot so removed messages do not linger.
  • Refresh rendered strings after locale, context or datafile changes. Use the SDK's events to connect updates to your application state.
  • Let the application choose layouts and accessibility direction. Translation evaluation does not automatically mirror Android views for RTL locales.
  • Call m.close() when its owner is permanently disposed. An Activity owned instance can close in onDestroy; an application or ViewModel owned instance needs the corresponding longer lifetime.
  • Cancel pending loads and prevent late results from updating a destroyed screen. Close any replacement instance that is no longer needed.

The example's explicit New York time zone makes the demonstration reproducible. Choose the user or product time zone deliberately in your application.

Example application

The messagevisor-example-android application demonstrates loading, error and retry states, plain translations and a formatted closing time. MainActivity.kt contains the integration and closes the SDK when the Activity is destroyed.

Previous
Java
Next
Swift