Skip to main content

Usage

Quickstart​

  1. Ensure you have completed Installation and Initialization in your Application class. See: Installation

  2. Wrap your Activity context so Android resource lookups (getString, etc.) use Tolgee:

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

TIP: If you use AppCompatActivity, the same approach applies. Wrap the base context in attachBaseContext.

  1. (If preferred) Recreate the Activity when translations change:
class MyActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val tolgee = Tolgee.instance
        lifecycleScope.launch {
            tolgee.changeFlow.collect {
                // Locale or translations changed
                recreate()
            }
        }
    }
}

or using good old listener:

class MyActivity : Activity(), Tolgee.ChangeListener {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        tolgee.addChangeListener(this)
    }

    override fun onDestroy() {
        super.onDestroy()
        tolgee.removeChangeListener(this)
    }

    override fun onTranslationsChanged() {
        recreate()
    }
}
  1. Fetch and display a translation with a safe fallback to your Android resources:
val tolgee = Tolgee.instance
val text = tolgee.t(context, R.string.string_key)
textView.text = text

With Parameters​

Provide arguments for placeholders in your strings:

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

TIP: Parameters map to Android-style placeholders in order (e.g., %1$s, %2$d).

Plurals​

Handle Android plurals via resources:

val itemsText = tolgee.tPlural(context, R.plurals.items_count, count, count)
textView.text = itemsText

NOTE:

  • The second count argument is the formatting parameter used inside the string (typical Android pattern when you want to show the number).
  • Tolgee resolves the key from your Android resource ID using resources.getResourceEntryName. Ensure the keys exist in Tolgee Platform as well.
  • Limitation: Only one plural per string is supported (Android plural resources). Nested or multiple plurals in a single string are not supported.

Language Switching​

Set locale:

tolgee.setLocale("en")

Get current locale:

val locale = tolgee.getLocale()

Listen for changes:

tolgee.changeFlow.collect {
    // Locale or available translations changed, update UI if needed
}

Advanced Configuration​

Formatter Configuration​

Configure formatters for parsing translations from CDN:

Tolgee.init {
    contentDelivery {
        url = "https://cdn.tolg.ee/your-cdn-url-prefix"
        format(Tolgee.Formatter.Sprintf) // Android SDK formatting (default)
        // format(Tolgee.Formatter.ICU) // Tolgee Native Flat JSON formatting
    }
}

Preloading Translations​

Preload translations for the current locale from Activity:

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

Reactive lookups with tFlow​

You can also use tFlow to reactively update a specific string when translations change:

lifecycleScope.launch {
  tolgee.tFlow(context, R.string.string_key).collect { text ->
    textView.text = text
  }
}

TIP: tFlow updates when locale or available translations change. This can be used for live updates without the need for full activity recreate.

Obtaining a Tolgee instance​

Most apps use the singleton:

val tolgee = Tolgee.instance

For DI or testing, you can hold a reference you created during initialization and pass it around explicitly.

Reactive UI updates​

If your UI should react to translation/locale changes, subscribe to changeFlow and update state accordingly. See Compose examples in Jetpack Compose Usage.

Best practices​

  • Preload translations in onStart for Activities or when a Fragment becomes visible.
  • Avoid blocking calls on the main thread; use flows for reactivity.
  • Keep keys in sync between Android resources and Tolgee Platform.

Next steps​