Internationalization in CMP

Learn how to create a basic implementation of field-level translation in a Compose Multiplatform (CMP) project.

Setup

In your space, open Settings → Internationalization → Languages and add es (Spanish).

• In the article content type block schema, set the title and content fields as translatable.
• Open each article, select the Spanish language, and provide translated content. You can also use AI Translations.

Note

Learn more in the internationalization concept.

Use the device locale

Update App.kt to determine the language from the device locale.

shared/src/commonMain/kotlin/org/example/project/App.kt

…
import androidx.navigation3.runtime.entryProvider
import androidx.compose.ui.text.intl.LocaleList
…
      val backStack = rememberNavBackStack(NavConfiguration, initialStoryKey)

      val availableLanguages = listOf("es")
      val language = LocaleList.current.localeList
        .map { it.language }
        .firstOrNull { it in availableLanguages }

      Storyblok(
        accessToken = "YOUR_ACCESS_TOKEN",
        version = contentVersion,
        region = EU, // Choose the correct region from your Space.
        language = language,
        …
      ) {
        …
      }
…

First, availableLanguages lists the language codes configured in the space.

Next, LocaleList.current returns the user’s preferred locales in priority order. The first locale whose language is in availableLanguages becomes the language parameter of the Storyblok composable function. If no locale matches, language stays null and the API returns the space’s default language.

Note

LocaleList is part of Compose’s multiplatform text API, so this same code works on Android, iOS, and web—unlike LocalConfiguration, which exists only on Android.

Tip

Use the fallbackLanguage parameter of the Storyblok composable function to specify which language to fall back to for fields that have not been translated yet.

Test on each target

Each target changes the language differently:

• Android: change the device language under Settings → System → Languages, or set a per-app language preference. The configuration change recreates the composition and the stories are re-fetched automatically.
• iOS: change the language in Settings → General → Language & Region, or set a per-scheme language in Xcode. The app restarts.
• Web: change the language in the browser settings, then reload the page.

The app now renders the translated article content.

Note

Internationalization is highly implementation-specific. Instead of relying on the device locale, you may, for example, want to offer an in-app language picker and store the selection, passing it as the language parameter. That approach also behaves consistently across all three targets.

Related resources

Concept: Internationalization

Storyblok Composable Function Reference

Kotlin: Localize Strings in Compose Multiplatform