Skip to main content

Installation

NOTE: For managing static translations, we recommend using Tolgee CLI.

Requirements​

  • Android API Level: 21+ (Android 5.0+)

Quickstart (Views)​

  1. Add dependency (Core):

    Using Version Catalog is recommended to keep your versions aligned.

    # gradle/libs.versions.toml
    [libraries]
    tolgee = { group = "io.tolgee.mobile-kotlin-sdk", name = "core", version.ref = "tolgee" }
    // build.gradle.kts (module)
    dependencies {
        implementation(libs.tolgee)
    }

    If you use Jetpack Compose, see the Compose variant: Jetpack Installation

  2. (If needed) Ensure repositories include Maven Central:

    // settings.gradle.kts or build.gradle.kts
    pluginManagement { repositories { gradlePluginPortal(); google(); mavenCentral() } }
    dependencyResolutionManagement { repositories { google(); mavenCentral() } }

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

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

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

  • Open Tolgee Platform → your Project → Developer settings → Content Delivery.
  • Copy the full CDN URL prefix. 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/404, double‑check the prefix.

TIP: For Activities, wrap the base context so getString and similar APIs use Tolgee. See step-by-step in Usage.

Next steps​