Skip to main content

Usage (Compose Module)

This guide shows you how to use the Tolgee Android SDK Compose module in Jetpack Compose and Compose Multiplatform applications. For traditional Android Views usage, see Android Views Usage.

Prerequisites​

Make sure you've completed the quickstart setup and initialized Tolgee for Compose. See: Installation (Compose Module)

Basic Usage​

Tolgee's Compose extensions let you fetch localized keys directly inside your composables. Unlike traditional Android Views which require manual UI updates or Activity recreation, Compose integration automatically recomposes UI elements when translations change.

note

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

Getting translations​

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 function with Res.

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

With Parameters​

Pass parameters to translations, supply arguments for placeholders in your keys.

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

Plurals​

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

  • Jetpack Compose
@Composable
fun PluralText(count: Int) {
    // First 'count' parameter determines which plural form to use
    // Second 'count' parameter is passed as a value to the translation
    Text(text = pluralStringResource(R.plurals.items_count, count, count))
}
  • Compose Multiplatform
@Composable
fun PluralText(count: Int) {
    Text(text = pluralStringResource(Res.plurals.items_count, count, count))
}

Example plural resource:

<!-- In res/values/plurals.xml -->
<plurals name="items_count">
    <item quantity="one">%d item</item>
    <item quantity="other">%d items</item>
</plurals>

The pluralStringResource function will:

  1. Select the correct plural form based on the count value
  2. Replace the placeholder with the provided value
  3. Automatically update the UI if the count changes or if translations are updated

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

Explicit Tolgee Instance​

@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 currentLocale = tolgee.changeFlow.mapLatest {
        tolgee.getLocale()
    }.collectAsState(initial = tolgee.getLocale())

    Row {
        Text(text = stringResource(tolgee, R.string.selected_locale, currentLocale.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.

How Compose Integration Differs from Android Views​

Tolgee's Compose integration offers several advantages over traditional Android Views:

Reactive by default - Compose UI automatically updates when translations change, without manual intervention

No Activity recreation needed - Unlike Android Views which require recreate() to refresh translations

Simplified API - Familiar stringResource() and pluralStringResource() functions that match Compose's built-in functions

State-based - Translations are part of the Compose state system, ensuring proper recomposition

Multiplatform support - Works with both Jetpack Compose for Android and Compose Multiplatform

Example Projects​

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

Next Steps​