Skip to main content

Usage (Compose Module)

This guide shows you how to use the Tolgee Android SDK Compose module in your Jetpack Compose or Compose Multiplatform application.

Prerequisites​

Make sure you've completed the quickstart setup and initialized Tolgee for Compose. See: Compose Quickstart

Basic Usage​

Tolgee's Compose extensions let you fetch localized strings directly inside your composables.

1. Simple Strings​

  • Jetpack Compose
@Composable
fun SimpleText() {
    Text(text = stringResource(R.string.welcome_message))
}
  • Compose Multiplatform
@Composable
fun SimpleText() {
    Text(text = stringResource(Res.string.welcome_message))
}
info

In the Compose Multiplatform use stringResource extension function with Res.

Use stringResource for simple strings (e. g., error messages, titles) - retrieve a translation by its resource ID.

2. With Parameters​

Pass parameters to translations - supply arguments for placeholders in your strings.

  • Jetpack Compose
@Composable
fun TextWithParameters(name: String) {
    Text(text = stringResource(R.string.welcome_user, name))
}
  • Compose Multiplatform
@Composable
fun TextWithParameters(name: String) {
    Text(text = stringResource(Res.string.welcome_user, name))
}

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

3. Plurals​

Handle plurals with pluralStringResource - provide the count and any formatting args.

  • Jetpack Compose
@Composable
fun PluralText(count: Int) {
    Text(text = pluralStringResource(R.plurals.item_count, count, count))
}
  • Compose Multiplatform
@Composable
fun PluralText(count: Int) {
    // Handle plural forms
    Text(text = pluralStringResource(Res.plurals.item_count, count, count))
}

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

Explicit Tolgee Instance​

If you need to use a specific Tolgee instance (not the singleton), you can pass it explicitly:

@Composable
fun ExplicitInstance() {
    val tolgee = remember { myCustomTolgee }

    Text(text = stringResource(tolgee, R.string.welcome_message))
}

Handy when you need more than one instance (multiple projects/CDNs), when following dependency injection patterns (dependencies are “injected”, not created inside classes), and or during testing/previews.

Locale Switching​

You can create a locale switcher component:

@Composable
fun LocaleSwitcher() {
    val tolgee = Tolgee.instance
    val locale by tolgee.changeFlow
        .map { tolgee.getLocale() }
        .collectAsState(initial = tolgee.getLocale())

    Row {
        Text(text = stringResource(tolgee, R.string.selected_locale, locale.language))
        Button(onClick = { tolgee.setLocale("en") }) {
            Text("English")
        }
        Button(onClick = { tolgee.setLocale("fr") }) {
            Text("Français")
        }
        Button(onClick = { tolgee.setLocale("cs") }) {
            Text("Čeština")
        }
    }
}

Handy for apps, where “choose language” option is available, you want to use Over‑the‑Air (OTA) translation updates (translations refresh automatically when locale or content changes), and during testing/debugging. Most often used in settings screens, onboarding flows, or debug menus - anytime you want to allow runtime language switching.

Observing Locale Changes​

Collecting Tolgee.changeFlow as state ensures your composable recomposes whenever the locale changes, keeping the UI in sync with the active language.

@Composable
fun LocaleAwareComponent() {
    val tolgee = Tolgee.instance

    val locale by tolgee.changeFlow
        .map { tolgee.getLocale() }
        .collectAsState(initial = tolgee.getLocale())

    Text(text = locale.language)
}

Handy for observing locale changes in real time, keeping track of current locale, showing chosen language in app, reactively updating translations whenever user switches the language.

Next Steps​