Skip to main content

Usage (Core Module)

Prerequisites​

Ensure you have completed the quickstart setup and initialization in your Application class. See: Quickstart

Basic Usage​

Get the global Tolgee instance:​

val tolgee = Tolgee.instance

From now on you can use:

  • translations: tolgee.t("key"), tolgee.tFlow("key"),
  • change system: tolgee.changeFlow,
  • locale changes: tolgee.setLocale("cs").

Getting Translations​

1. One time translations:​

val text: String? = tolgee.t("key")

Returns null if isn’t loaded yet (e.g.,SDK hasn't downloaded data)

Returns string when loaded.

Use for simple/static text (e. g., error messages, titles).

Get a translation with fallback to Android resources​

val text = tolgee.t(context, R.string.string_key)
info

Fallbacks provide a safety net in case of any problems with loading the translation or pulling from Android resources.

2. Translation with parameters:​

val textWithParams: String? = tolgee.t("key_with_param", mapOf("param" to "value"))

Use for translation with dynamic values. Add data that changes during the app's runtime (e.g., dates, numbers, usernames).

tip

Android-style strings, placeholders follow Sprintf order (e.g., %1$s, %2$d).

Get a translation with fallback to Android resources with parameters​

val textWithParams = tolgee.t(context, R.string.string_with_params, "param1", "param2")

Semi-dynamic updates for classic Views​

info

To receive fresh translations without needing to publish new app versions follow these steps:

a) Wrap your Activity context so Android resource lookups use Tolgee:

class MyActivity : Activity() {
    override fun attachBaseContext(newBase: Context?) {
        super.attachBaseContext(TolgeeContextWrapper.wrap(newBase))
    }
}

b) Trigger a UI refresh when locale/translations change:

lifecycleScope.launch {
    tolgee.changeFlow.collect {
        recreate() // reloads the Activity, Views get fresh translations
    }
}

Combining those two approaches gives semi-dynamic behavior: translations update after an Activity reload, not instantly. These methods can be used with ways mentioned above (a one-time translation and translations with parameters).

3. Get dynamic (reactive) translations.​

val textFlow: Flow<String> = tolgee.tFlow("key")
textFlow.collect { text ->
    // Use the text (e.g., update UI)
}

Use for reactive UI. Translations update immediately and automatically whenever the language or CDN data changes.

Get a reactive translation with fallback to Android resources​

val textFlow = tolgee.tFlow(context, R.string.string_key)

tip

In Compose, use collectAsState() function for a more idiomatic integration. See more in Jetpack Compose Usage.

Plurals​

info

Tolgee advantage: keeps plural rules and translations in sync across languages, without you needing to hardcode them.

Handle Android plurals via resources:
val itemsText = tolgee.tPlural(context, R.plurals.items_count, count, count)
textView.text = itemsText

Use for lists, counters, notifications — any situation where the grammar changes with quantity.

Locale Management​

1. Set the locale manually.​

tolgee.setLocale("en")

Use when your app lets users pick a locale.

tip

Combine this with recreate() after language changes. This reloads your Activity and ensures Views show updated translations.

2. Get the current locale​

val locale = tolgee.getLocale()

Use for checking what locale is working currently. Handy for displaying the current locale, debugging, or syncing with app/system settings.

3. Listen for locale/translation changes​

lifecycleScope.launch {
    tolgee.changeFlow.collect {
        // locale or available translations changed
    }
}

Use for building dynamically updated UI. Enables you to create UI that stays in sync with locale changes and new translations.

Advanced Configuration​

Formatter Configuration​

Choose how placeholders are parsed and rendered. Use when you have translations with placeholders, SDK must know how to exchange the placeholders for wanted values. Example: "Hello %s" or"You have {count} items"

  1. Sprintf (default – Android style)
Tolgee.init {
    contentDelivery {
        url = "https://cdn.tolg.ee/your-cdn-url-prefix"
        format(Tolgee.Formatter.Sprintf)
    }
}

Use for easy scenarios, when you are using classic formatters (%s, %d, %1$s).

  1. ICU (advanced)
Tolgee.init {
    contentDelivery {
        url = "https://cdn.tolg.ee/your-cdn-url-prefix"
        format(Tolgee.Formatter.ICU)
    }
}

Use for more advanced translations, when you need formatters like (few, may, female, complex lingual principles).

Preload translations for the current locale from Activity​

override fun onStart() {
  super.onStart()
  tolgee.preload(this)
}

Improves perceived performance and avoids empty/late. Use for UI’s where the translations are critical (e.g., login, onboarding).

Example Projects​

For complete examples of how to use the Tolgee Core module, check out the demo projects:

Example Android- https://github.com/tolgee/tolgee-mobile-kotlin-sdk/tree/master/demo/exampleandroid .

Best Practices​

  • Preload translations in onStart/Fragment visibility → prevents blank UI.
  • Avoid main-thread blocking; use Flows → keeps UI responsive.
  • Keep keys in sync between Android resources and Tolgee → avoids fallback issues.
  • Wrap context in Activities → automatic updates in classic Views.
  • Subscribe to changeFlow → enables fully reactive UIs.

Next Steps​