Use localizations and locale codes in Kotlin Multiplatform SDK

Why this is important

Locale codes come into play when Adapty picks the localization for a flow or an onboarding, and when you read a remote config for a custom paywall.

Locale codes are complicated and can vary from platform to platform, so Adapty relies on one internal standard across every platform it supports. Understanding that standard helps you predict which localization a user receives.

Locale code standard at Adapty

For locale codes, Adapty uses a slightly modified BCP 47 standard: every code consists of lowercase subtags, separated by hyphens. Some examples: en (English), pt-br (Portuguese (Brazil)), zh (Simplified Chinese), zh-hant (Traditional Chinese).

Locale code matching

In SDK v4, flows and onboardings match locale codes differently: flows are localized by the SDK on the device, onboardings by the Adapty server.

Flows and Paywall Builder paywalls

A paywall built in the Paywall Builder is delivered as a flow in SDK v4, so the rule below covers both.

The match is exact. The SDK compares the code you pass with the localization codes of the flow character by character: it doesn’t change the case, doesn’t replace underscores (_) with hyphens (-), and doesn’t fall back to the language subtag. For a flow with a pt-br localization, only pt-br matches: pt-BR, pt_BR, and pt-PT all miss.

When the code matches no localization, the flow silently renders in its default locale — the SDK doesn’t return an error and doesn’t log a warning.

When the code matches, Adapty merges the localization with the default one: the strings and assets that the matched localization doesn’t define come from the default localization.

Omitting the locale code is not the same as asking for the flow’s default localization: the SDK substitutes a fixed en. A flow whose default locale is de still renders in en when it has an en localization, and falls back to de only when it doesn’t.

Pass the locale code exactly as it’s configured in the dashboard — lowercase subtags separated by hyphens. Don’t pass a platform locale identifier as is: on Android, Locale.getDefault().toLanguageTag() returns pt-BR; on iOS, NSLocale.currentLocale.localeIdentifier returns pt_BR. Both fall back to the default localization. Convert the value in your app before you pass it.

Onboardings

Onboardings are localized on the server, and the server rules tolerate other formats. When you pass a locale to getOnboarding:

The locale string is converted to lowercase and all the underscores (_) are replaced with hyphens (-)
Adapty looks for the localization with the fully matching locale code
If no match is found, Adapty takes the substring before the first hyphen (pt for pt-br) and looks for the matching localization
If no match is found again, Adapty returns the content for the onboarding’s default locale

This way pt_BR, pt-BR, and pt-br all resolve to the same onboarding localization.

Implementing localizations

In SDK v4, you don’t pass a locale code when you fetch a flow — getFlow returns the flow with all of its localizations, and Adapty applies one when the flow view is built.

Flows built in the builder: the SDK doesn’t read the device locale, so resolve it in your app and pass it as the locale parameter of createFlowView. It’s optional — omit it and the flow renders in en, or in its default locale when the flow has no en localization.
```
import com.adapty.kmp.AdaptyUI

AdaptyUI.createFlowView(flow = flow, locale = "es")
    .onSuccess { view ->
        view.present()
    }
    .onError { error ->
        // handle the error
    }
```
createNativeFlowView and the AdaptyUIFlowPlatformView composable take the same optional locale parameter. view.locale reports the localization the view was built with. Both the locale parameter and view.locale require Kotlin Multiplatform SDK 4.0.1-beta.1 or later.
Custom (remote config) paywalls: getFlow returns every configured localization in flow.remoteConfigs. Each entry is an AdaptyRemoteConfig with a locale code and a dataMap. Select the entry that matches the user, with your own fallback:

import com.adapty.kmp.Adapty

Adapty.getFlow("YOUR_PLACEMENT_ID")
    .onSuccess { flow ->
        val config = flow.remoteConfigs.firstOrNull { it.locale == "en" }
            ?: flow.remoteConfigs.firstOrNull()
        // read your values from config?.dataMap
    }
    .onError { error ->
        // handle the error
    }

Adapty stores those locale codes in the format described in Locale code standard at Adapty. The SDK doesn’t match remote configs against a locale, so which entry to apply is up to your app.

Why this is important

There are a few scenarios when locale codes come into play — for example, when you’re trying to fetch the correct paywall for the current localization of your app.

As locale codes are complicated and can vary from platform to platform, we rely on an internal standard for all the platforms we support. However, because these codes are complicated, it is really important for you to understand what exactly are you sending to our server to get the correct localization, and what happens next — so you will always receive what you expect.

Locale code standard at Adapty

Locale code matching

When Adapty receives a call from the client-side SDK with the locale code and starts looking for a corresponding localization of a paywall, the following happens:

The incoming locale string is converted to lowercase and all the underscores (_) are replaced with hyphens (-)
We then look for the localization with the fully matching locale code
If no match was found, we take the substring before the first hyphen (pt for pt-br) and look for the matching localization
If no match was found again, we return the content for the paywall’s default locale

This way an iOS device that sent 'pt_BR', an Android device that sent pt-BR, and another device that sent pt-br will get the same result.

Implementing localizations: recommended way

If you’re wondering about localizations, chances are you’re already dealing with localized string resources in your project. If that’s the case, we recommend placing some key-value with the intended Adapty locale code in each of your resource files for the corresponding localizations. And then extract the value for this key when calling our SDK, like so:

// 1. Add the Adapty locale code to your Compose Multiplatform resources

/*
composeResources/values/strings.xml (default — English)
*/
<string name="adapty_paywalls_locale">en</string>

/*
composeResources/values-es/strings.xml (Spanish)
*/
<string name="adapty_paywalls_locale">es</string>

/*
composeResources/values-pt-rBR/strings.xml (Portuguese — Brazil)
*/
<string name="adapty_paywalls_locale">pt-br</string>

// 2. Extract and use the locale code
import com.adapty.kmp.Adapty
import yourapp.composeapp.generated.resources.Res
import yourapp.composeapp.generated.resources.adapty_paywalls_locale
import org.jetbrains.compose.resources.getString

suspend fun fetchPaywall() {
    val locale = getString(Res.string.adapty_paywalls_locale)
    Adapty.getPaywall(
        placementId = "YOUR_PLACEMENT_ID",
        locale = locale
    ).onSuccess { paywall ->
        // the requested paywall
    }.onError { error ->
        // handle the error
    }
}

That way you can ensure you’re in full control of what localization will be retrieved for every user of your app.

If you don’t use Compose Multiplatform resources, the same idea applies to any localization library you do use (for example, moko-resources) — store the Adapty locale code as a string in each locale’s resource bundle and read it before calling the SDK.

Implementing localizations: the other way

You can get similar (but not identical) results without explicitly defining locale codes for every localization. That would mean extracting a locale code directly from the device — which requires expect/actual declarations, since there is no shared locale API in commonMain:

// commonMain
expect fun currentLocaleTag(): String

// androidMain
import java.util.Locale
actual fun currentLocaleTag(): String = Locale.getDefault().toLanguageTag()

// iosMain
import platform.Foundation.NSLocale
import platform.Foundation.currentLocale
import platform.Foundation.localeIdentifier
actual fun currentLocaleTag(): String = NSLocale.currentLocale.localeIdentifier

// commonMain — pass the locale code to Adapty
import com.adapty.kmp.Adapty

suspend fun fetchPaywall() {
    Adapty.getPaywall(
        placementId = "YOUR_PLACEMENT_ID",
        locale = currentLocaleTag()
    ).onSuccess { paywall ->
        // the requested paywall
    }.onError { error ->
        // handle the error
    }
}

Note that we don’t recommend this approach due to few reasons:

On iOS, the user’s preferred language and the device’s regional locale are not identical. NSLocale.currentLocale.localeIdentifier returns the regional locale, which may differ from the language users actually read your app in. iOS apps that use localized string files rely on Apple’s resolution logic to combine both — which works out of the box with the recommended approach above.
It’s hard to predict what exactly the device will return and whether it matches an Adapty localization. The device locale may include extensions or regional codes you haven’t configured in Adapty, in which case the SDK falls back to the first-subtag match or, ultimately, to en.

Should you decide to use this approach anyway — make sure you’ve covered all the relevant use cases.