translationtools-client-kmp is a Kotlin Multiplatform client for TranslationTools.

It keeps Android strings.xml as the source of truth, generates typed Translations.* accessors for shared code, bundles fallback translations into your app, and refreshes translations from TranslationTools at runtime.

Use it when you want all of this at once:

• keep editing normal Android XML string resources
• use the same typed translation API from shared KMP code
• ship local fallback strings with the app
• fetch updated translations from TranslationTools without changing call sites

Current scope:

• supports Android XML <string> resources
• generates Translations.* and TranslationsBundledSnapshot
• supports Android, JVM, and iOS consumers through the KMP client
• skips <plurals> and <string-array>
• optionally syncs Apple .strings files (InfoPlist.strings, Localizable.strings) as a second source of truth — sync-only: push/pull plus the bundled .lproj files, with no generated Translations.* accessors and no runtime refresh (see Apple .strings (iOS))

Maven Central:

https://repo1.maven.org/maven2/io/mvdm/translationtools/translationtools-client-kmp/2.1.0/

Repository:

repositories {
    mavenCentral()
}

Runtime client:

dependencies {
    implementation("io.mvdm.translationtools:translationtools-client-kmp:2.1.0")
}

Optional Compose helpers:

dependencies {
    implementation("io.mvdm.translationtools:translationtools-client-compose:2.1.0")
}

Version catalog:

[libraries]
translationtools-client-kmp = { module = "io.mvdm.translationtools:translationtools-client-kmp", version = "2.1.0" }
translationtools-client-compose = { module = "io.mvdm.translationtools:translationtools-client-compose", version = "2.1.0" }

dependencies {
    implementation(libs.translationtools.client.kmp)
}

To generate Translations.*, your module also needs the io.mvdm.translationtools.plugin Gradle plugin. That plugin reads Android XML and generates the typed resource API used by this client.

The plugin is not yet published to a repository. Include it as a composite build from your consumer project. Copy or clone the gradle/translationtools-plugin directory, then add it to your settings.gradle.kts:

pluginManagement {
    includeBuild("path/to/translationtools-plugin")

    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

Then apply it in your module:

plugins {
    id("io.mvdm.translationtools.plugin")
}

Compatibility: the plugin is compiled with Kotlin 2.1.20 and works with Gradle 8.x and 9.x. Consumer projects can use any Kotlin version from 1.9.25 through current 2.x releases.

1. You keep strings in src/androidMain/res/values*/**/*.xml.
2. The Gradle plugin generates Kotlin resources such as Translations.home_title.
3. The build also generates TranslationsBundledSnapshot, a bundled fallback snapshot from your local XML.
4. Your app creates TranslationToolsClient and calls initialize().
5. The client restores cached or bundled translations, then refreshes from TranslationTools.
6. Your code reads translations through Translations.*.

plugins {
    id("org.jetbrains.kotlin.multiplatform")
    id("com.android.library")
    id("io.mvdm.translationtools.plugin")
}

The runtime dependency alone does not generate resources.

Example src/androidMain/res/values/strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="home_title">Home</string>
    <string name="checkout_title">Checkout</string>
</resources>

Example src/androidMain/res/values-nl/strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="home_title">Start</string>
    <string name="checkout_title">Afrekenen</string>
</resources>

apiKey: your-project-api-key
defaultLocale: en
locales:
  - en
  - nl
generated:
  packageName: com.example.translations
androidResources:
  resourceDirectories:
    - src/androidMain/res
  keyOverrides: {}
# Optional — only if you also sync Apple .strings files (see "Apple .strings (iOS)").
# appleResources:
#   resourceDirectories:
#     - ../iosApp/iosApp

defaultLocale and locales are shared across both platforms. The appleResources block is optional; omitting it leaves the build Android-only and unchanged.

API key lookup order (Gradle plugin):

1. Gradle property -Ptranslationtools.apiKey=...
2. Environment variable TRANSLATIONTOOLS_API_KEY
3. apiKey in translationtools.yaml

The runtime client also needs the API key to refresh translations at app startup. On Android, a common approach is to expose it via BuildConfig:

// androidApp/build.gradle.kts
buildTypes {
    debug {
        buildConfigField("String", "TRANSLATION_TOOLS_API_KEY",
            "\"${localProperties.getProperty("TRANSLATIONTOOLS_API_KEY") ?: System.getenv("TRANSLATIONTOOLS_API_KEY") ?: ""}\"")
    }
}

Then set the key in local.properties (not committed to version control):

TRANSLATIONTOOLS_API_KEY=your-project-api-key

Pass it when creating the client:

TranslationToolsClientOptions(
    apiKey = BuildConfig.TRANSLATION_TOOLS_API_KEY,
    backgroundRefreshEnabled = BuildConfig.TRANSLATION_TOOLS_API_KEY.isNotBlank(),
    // ...
)

Without a valid API key, backgroundRefreshEnabled should be false and the app will only use bundled fallback translations.

./gradlew.bat generateTranslationResources

This generates:

• Translations.* for typed string access
• TranslationsBundledSnapshot for bundled fallback data

The plugin also wires generation into Kotlin compilation, so normal builds regenerate resources automatically.

Common shape:

import io.ktor.client.HttpClient
import io.mvdm.translationtools.client.TranslationTools
import io.mvdm.translationtools.client.TranslationToolsClientOptions

JVM example:

import com.example.translations.TranslationsBundledSnapshot
import io.ktor.client.HttpClient
import io.mvdm.translationtools.client.JvmTranslationSnapshotStores
import io.mvdm.translationtools.client.TranslationTools
import io.mvdm.translationtools.client.TranslationToolsClientOptions

val client = TranslationTools.createClient(
    httpClient = HttpClient(),
    options = TranslationToolsClientOptions(
        apiKey = "your-project-api-key",
        currentLocaleProvider = { "en" },
        snapshotStore = JvmTranslationSnapshotStores.default(),
        bundledSnapshot = TranslationsBundledSnapshot.value,
    ),
)

Android example:

import android.content.Context
import com.example.translations.TranslationsBundledSnapshot
import io.ktor.client.HttpClient
import io.mvdm.translationtools.client.AndroidTranslationSnapshotStores
import io.mvdm.translationtools.client.TranslationTools
import io.mvdm.translationtools.client.TranslationToolsClientOptions

fun createTranslationsClient(context: Context) = TranslationTools.createClient(
    httpClient = HttpClient(),
    options = TranslationToolsClientOptions(
        apiKey = "your-project-api-key",
        currentLocaleProvider = {
            context.resources.configuration.locales[0].toLanguageTag()
        },
        snapshotStore = AndroidTranslationSnapshotStores.fromContext(context),
        bundledSnapshot = TranslationsBundledSnapshot.value,
    ),
)

suspend fun startTranslations() {
    client.initialize()
}

initialize() does this:

• restore persisted snapshot when available
• otherwise restore bundled snapshot from generated XML data
• otherwise do a blocking remote refresh
• after restore, optionally do a background refresh

import com.example.translations.Translations

val cachedTitle = client.getCached(Translations.home_title)
val title = client.get(Translations.home_title)
val titleUpdates = client.observe(Translations.home_title)

Behavior:

• getCached(...) returns cached value, otherwise XML fallback, otherwise the key
• get(...) returns cached value first and fetches from TranslationTools on cache miss
• observe(...) exposes a Flow that updates when translations change

Locale resolution order:

1. explicit locale argument
2. currentLocaleProvider
3. project default locale
4. en

If you use Compose, add translationtools-client-compose and provide the client through composition locals.

Compose artifact targets:

• android
• jvm
• iosX64
• iosArm64
• iosSimulatorArm64

import androidx.compose.runtime.CompositionLocalProvider
import com.example.translations.Translations
import io.mvdm.translationtools.client.compose.LocalTranslationToolsClient
import io.mvdm.translationtools.client.compose.LocalTranslationToolsLocale
import io.mvdm.translationtools.client.compose.stringResource

CompositionLocalProvider(
    LocalTranslationToolsClient provides client,
    LocalTranslationToolsLocale provides "en",
) {
    val title = stringResource(Translations.home_title)
}

Available Gradle tasks:

• ./gradlew.bat initTranslationTools Creates a starter translationtools.yaml.
• ./gradlew.bat generateTranslationResources Generates Translations.* and TranslationsBundledSnapshot from local XML.
• ./gradlew.bat pushTranslations Uploads local XML — and, when appleResources is configured, Apple .strings — to TranslationTools.
• ./gradlew.bat pullTranslations Downloads translations from TranslationTools, updates local XML (and Apple .strings), then regenerates Kotlin resources.

generateTranslationResources stays Android-only; it never reads Apple .strings.

Normal workflow:

1. Edit src/androidMain/res/values*/**/*.xml.
2. Build or run generateTranslationResources.
3. Use Translations.* in shared or platform code.
4. Run pushTranslations when local XML should become the remote state.
5. Run pullTranslations when remote changes should be merged back into XML.

iOS apps ship localized copy outside Android XML — Apple .strings files such as InfoPlist.strings (app display name, permission usage descriptions) and Localizable.strings, living in <locale>.lproj/ directories. You can manage these in TranslationTools as a second source of truth alongside Android XML.

Point the plugin at the directories that contain your .lproj/ folders (paths may resolve outside the Gradle module, e.g. an Xcode app target beside the shared module):

appleResources:
  resourceDirectories:
    - ../iosApp/iosApp

Every .strings file inside the discovered .lproj/ folders is then auto-discovered and included in pushTranslations / pullTranslations. There is no per-key opt-out.

Behavior:

• Origins. Each filename is its own origin (:/InfoPlist.strings, :/Localizable.strings), parallel to :/strings.xml, so identical keys across platforms never collide.
• Locales. .lproj names map to the shared lowercase-hyphen locale axis: en.lproj → en, pt-BR.lproj (and legacy pt_BR) → pt-br, Base.lproj → defaultLocale. If both Base.lproj and an explicit default-locale directory exist, the explicit one wins and a warning is emitted. Write-back uses Apple's conventional casing (pt-BR.lproj).
• Codec. Reads UTF-8 and UTF-16 (BOM detection); writes UTF-8 without a BOM. Handles standard escapes (\", \\, \n, \t, \Uxxxx). Unparseable lines are warned-and-skipped, never fatal.
• Pull is preserve-on-merge. Existing keys are updated in place; new keys are appended; comments, blank lines, and ordering are kept. A missing remote locale's .lproj/<file>.strings is created (with a managed-by-TranslationTools header) plus a warning to add the region to your Xcode project's knownRegions — the plugin does not edit project.pbxproj.

Sync-only, by design. Apple .strings get no generated Translations.* accessors and are not part of TranslationsBundledSnapshot; the .lproj/*.strings files in the signed app bundle are themselves the iOS bundled fallback. There is no runtime refresh for these keys, because the OS (InfoPlist.strings) and native code (NSLocalizedString) read them from the read-only bundle — there is no delivery path for a runtime-fetched value. Making app-owned iOS UI text runtime-updatable (routing native reads through the KMP client) is a separate, larger initiative. See docs/adr/0001 and docs/adr/0002.

.xcstrings (String Catalogs) are not supported.

If your app already uses Android strings.xml, migration is mostly mechanical.

• your existing src/androidMain/res/values*/strings.xml files
• your existing string names such as home_title
• Android XML as the editable source of truth

• generated resources become Translations.*
• runtime reads go through TranslationToolsClient
• TranslationTools becomes the remote source for updates and sync

1. Keep your existing strings.xml files under src/androidMain/res/values*/.
2. Apply io.mvdm.translationtools.plugin to the module that owns those files.
3. Add translationtools.yaml.
4. Run ./gradlew.bat generateTranslationResources.
5. Create and initialize TranslationToolsClient.
6. Replace runtime-backed string reads with Translations.*.
7. Run ./gradlew.bat pushTranslations once to upload your current XML to TranslationTools.

Typical code migration:

// before
context.getString(R.string.home_title)

// after
client.get(Translations.home_title)

Compose migration:

// before
androidx.compose.ui.res.stringResource(R.string.home_title)

// after
io.mvdm.translationtools.client.compose.stringResource(Translations.home_title)

Shared code migration:

// before
"Home"

// after
client.get(Translations.home_title)

• only XML <string> entries are generated
• <plurals> and <string-array> are skipped and need separate handling
• generated files live under build/generated/...; do not edit them by hand
• moving a string to a different XML file changes its translation origin in TranslationTools

• Generated accessor renamed from Res.string.* to Translations.* (avoids clash with Compose's Res).
• Bundled snapshot renamed from ResBundledSnapshot to TranslationsBundledSnapshot.
• The generated.objectName key in translationtools.yaml has been removed. The generated object is always named Translations. Remove objectName from your config.
• In call sites, replace Res.string.foo with Translations.foo and update imports to <your.package>.Translations / <your.package>.TranslationsBundledSnapshot.

For a complete production setup, make sure all of these are true:

1. translationtools-client-kmp is in your dependencies.
2. io.mvdm.translationtools.plugin is applied to the module with Android XML resources.
3. translationtools.yaml exists in the project root.
4. Your default locale XML exists in src/androidMain/res/values/.
5. Your app creates one TranslationToolsClient and calls initialize() at startup.
6. Your app reads translations through Translations.*.
7. You use pushTranslations and pullTranslations to sync local XML with TranslationTools.