Skip to main content

Usage

This guide shows you how to use the Tolgee Android SDK with traditional Android Views. For Jetpack Compose usage, see Jetpack Compose Usage.

Prerequisites​

Ensure you have completed the quickstart guide and initialized Tolgee in your Application class. See: Installation

Get The Global Tolgee Instance​

After you have initialized Tolgee in your app, following the quickstart guide. Set up a singleton Tolgee global instance, this allows you to use Tolgee.

val tolgee = Tolgee.instance

From now on you can:

  • get translations: tolgee.t("key"), tolgee.tFlow("key"),
  • change locales: tolgee.setLocale("xx"),
  • listen for changes: tolgee.changeFlow;

Getting Translations​

In this section, the translation types are demonstrated. Here you can see a quick overview:

note

If you are unsure of which translation type to choose, notice a “Use for...” section under every explanation.

One time translations:​

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

Returns null if translations are not yet loaded (e.g., SDK hasn't downloaded data). Returns a key when translations are loaded.

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

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

a) Preload translations for the current locale from Activity​

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

Improves perceived performance - ensures keys are ready sooner for the current locale.

Use for UI’s where the translations are critical (e.g., login, onboarding).

tip

Create a global corutine by calling tolgee.preload() function with mentioned above one-time translations and translations with parameters.

b) Get a translation with fallback to Android resources​

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

One time translation with fallbacks:

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

Translation with parameters & fallbacks:

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

To use parameters with Android fallbacks and ensure that translations from CDN can be interpreted, follow ICU order.

c) Semi-dynamic updates for classic Views​

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

  1. Wrap your Activity context so Android resource lookups use Tolgee:
class MyActivity : Activity() {
    override fun attachBaseContext(newBase: Context?) {
        super.attachBaseContext(TolgeeContextWrapper.wrap(newBase))
    }
}

The TolgeeContextWrapper intercepts all calls to getString(), getQuantityString(), and other resource methods, replacing them with Tolgee translations when available. This allows your existing Android code to use Tolgee translations without any changes to the code that calls getString().

  1. Trigger a UI refresh when locale or translations change:
lifecycleScope.launch {
    tolgee.changeFlow.collect {
        recreate() // reloads the Activity, Views get fresh translations
    }
}

Combining these two approaches gives you semi-dynamic behavior, translations update after an Activity reload, not instantly. This setup works with both one-time translations and translations with parameters.

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.

Dynamic translation with fallback to Android resources​

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

In Compose, use collectAsState() function for a more idiomatic integration.

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"

See also: Android XML format · Tolgee Universal ICU placeholders

1. Sprintf

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

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

warning

This parameter type won't work with fallbacks to Android Resources - it's not functional for apps with any offline activity.

2. ICU

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

Use for more advanced translations and ICU features, when you need nested formats or formatters, like e.g. few, may, female, and complex lingual principles.

Plurals​

Plurals ensure your app displays grammatically correct text based on the count, so users always see localized phrases.

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.

See also: Android XML format · Tolgee Universal ICU placeholders

Locale Management​

This section addresses deciding and controlling what language and region your app uses.

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.

Example Projects​

For a complete example of how to use the Tolgee Core module with Android Views, check out the demo project:

Example Android - Traditional Android Views example

Next Steps​