Skip to main content

Installation

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

CLI Project Init for Android Project​

https://docs.tolgee.io/tolgee-cli/project-configuration

More on Tolgee CLI file structure template for Android:

https://docs.tolgee.io/tolgee-cli/push-pull-strings#file-structure-template-format:~:text=The%20Android%20specific%20%7BandroidLanguageTag%7D%20placeholder%20is%20the%20same%20as%20%7BlanguageTag%7D%20but%20in%20Android%20format.%20(e.g.%2C%20en%2DrUS)

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
    [versions]
    tolgee = "1.0.0-alpha04" # replace with the desired version
    # ...
    [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() } }
  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>
            ... <!-- Add your own CDN domain if using self-hosted -->
            <!-- <domain includeSubdomains="true">example.com</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.

CDN configuration and Android SDK setup​

In the diagram below, you can find the general flow of how Android developers use the SDK is illustrated.

Tolgee Platform Setup​

In order to use translations in the app, make sure you have configured content delivery.

NOTE: When using Tolgee CLI and pushing strings.xml resource files, make sure you set up contentDelivery configuration in Tolgee.init as such

    path = { "values-$it/strings.xml" }

otherwise default is used which is "$it.json" and you will not see any updates in the app. See more in Installation and Usage docs.

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"

Initialize Tolgee in your Application class with json format (default)​

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

You should receive a 200 response. If you get 403/404, double‑check the prefix.

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

Initialize Tolgee with Android resources (strings.xml)​

In order to use Tolgee with XML resources, you need to specify the path pattern ending with strings.xml in the configuration. For example:

// in Application class
Tolgee.init {
      contentDelivery {
        url = "https://cdn.tolg.ee/083a55e896b5dcb9d358dc928e9f1234"
        path = { "values-$it/strings.xml" }
        storage = TolgeeStorageProviderAndroid(this@AndroidApp, BuildConfig.VERSION_CODE)
        availableLocales(availableLocales)
      }
      defaultLanguage("cs")
    }

You should receive a 200 response. If you get 403/404, double‑check the prefix.

curl -I "https://cdn.tolg.ee/your-cdn-url-prefix/values-cs/strings.xml"

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

More Resources​

Next steps​