Skip to main content

Quickstart (Compose Module)

This guide shows you how to integrate Tolgee Android SDK using the Compose module for Jetpack Compose and Compose Multiplatform.

The Compose module is Android’s modern declarative UI toolkit; it’s a simpler and more reactive model compared to Core module. It provides you with instant access to Tolgee translations directly in Composables/Compose Multiplatform projects, with automatic updates.

info

For managing static translations, we recommend using Tolgee CLI.

Requirements​

📱

Android API Level

Minimum API Level 21+ (Android 5.0 and above)

Dependency Setup​

info

Using Version Catalog is recommended to keep your versions aligned, especially in bigger projects. This provides readability, centralization, and consistency.

note

To build configuration examples use Kotlin DSL (build.gradle.kts). Groovy DSL may work but is not officially supported/tested.

  1. Add dependency (Compose):

In gradle/libs.versions.toml add an alias for Tolgee Compose library.

# gradle/libs.versions.toml
[libraries]
tolgee = { group = "io.tolgee.mobile-kotlin-sdk", name = "compose", version.ref = "tolgee" }

Then, in build.gradle.kts, use the created alias.

// build.gradle.kts (module)
dependencies {
    implementation(libs.tolgee)
}

For smaller projects you can also add dependency directly (the old way).

// build.gradle.kts
dependencies {
    implementation("io.tolgee.mobile-kotlin-sdk:compose:tolgee")
}
note

If you use traditional Android Views, see the Core variant: Core Quickstart

  1. (If needed) Ensure repositories include Maven Central:
// settings.gradle.kts or build.gradle.kts
pluginManagement { repositories { gradlePluginPortal(); google(); mavenCentral() } }
dependencyResolutionManagement { repositories { google(); mavenCentral() } }

Make sure your repositories are configured to include Maven Central for dependency resolution. If you encounter an error like:

Could not find io.tolgee.mobile-kotlin-sdk:compose

verify that Maven Central is included in your repository configuration.

  1. Allow CDN networking (required when using Tolgee Cloud CDN):

    Create a network security config file network_security.xml in your res/xml folder:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config xmlns:android="http://schemas.android.com/apk/res/android">
    <domain-config>
        <domain includeSubdomains="true">tolgee.io</domain>
        <domain includeSubdomains="true">tolg.ee</domain>
    </domain-config>
</network-security-config>

Add network security config to your AndroidManifest.xml:

<application
        android:networkSecurityConfig="@xml/network_security"> <!-- Add this line to your existing application tag -->
</application>
note

Allowing tolgee.io and tolg.ee domains is required when using Tolgee Cloud CDN. If you only access your own self-hosted CDN, include your domain(s) accordingly.

Initialization and configuration​

Initialize Tolgee in your Application class.

Android (Jetpack Compose)​

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Tolgee.init {
            contentDelivery {
                url = "https://cdn.tolg.ee/your-cdn-url-prefix" // from Tolgee Platform → Content Delivery
                storage = TolgeeStorageProviderAndroid(this@MyApplication, BuildConfig.VERSION_CODE) // cache invalidates on app update
            }
        }
    }
}

Multiplatform​

fun initTolgee() {
    Tolgee.init {
        contentDelivery {
            url = "https://cdn.tolg.ee/your-cdn-url-prefix"
            // Create a custom storage provider for caching the latest translations from CDN if needed
        }
    }
}

When your app boots up, Tolgee is globally initialized. The translations are downloaded from CDN and cached locally. Your Compose components can now use Tolgee without additional configuration.

Make sure that your app knows where to download translations:

For your app to download translation files, you need to provide a CDN URL prefix specific to your project. This prefix points to the catalog that contains your app's translations.

How to get your CDN URL prefix (Content Delivery):​

  1. Open Tolgee Platform → your Project → Developer settings → Content Delivery.
  2. Copy the full CDN URL prefix.
  3. You can use different prefixes per environment (dev/staging/prod).

Optional: Verify connectivity locally:​

curl -I "https://cdn.tolg.ee/your-cdn-url-prefix/en.json"

You should receive a 200 response. If you get 403 (Forbidden) or 404 (Not found), double‑check the prefix.

tip

Compose advantage: No context wrapping needed

Unlike traditional Android Views, Compose uses its own stringResource/pluralStringResource helpers, so no ContextWrapper is needed for automatic translation updates.

note

If you have a different integration setup (for example, using tolgee-cli and bundling JSON translation files in assets), the initialization may look different.

Next steps​