Skip to main content

Quickstart (Core Module)

info

For managing static translations, we recommend using Tolgee CLI.

Requirements​

📱

Android API Level

Minimum API Level 21+ (Android 5.0 and above)

Quickstart

This guide shows you how to integrate Tolgee Android SDK using the Core module for traditional Android Views.

The Core module is a Kotlin Multiplatform library that provides runtime support for Tolgee translations in your app. With Tolgee, you can update your translations over-the-air without releasing a new app version.

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 (Core):

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

# gradle/libs.versions.toml
[libraries]
tolgee = { group = "io.tolgee.mobile-kotlin-sdk", name = "core", 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:core:tolgee")
}
note

If you use Jetpack Compose, see the Compose variant: Jetpack Compose -> 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:core

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

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

When your app boots up, Tolgee is globally initialized. The translations are downloaded from CDN and cached locally. Other parts of your app (such as activities and fragments) 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).
info

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

Other Platforms​

For non-Android platforms, initialization is similar but without the Android-specific storage provider:

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

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

Dynamic updates without republishing. See the step-by-step guide in Usage.

Next steps​