Use localizations and locale codes in Android SDK

Why this is important

Locale codes come into play when Adapty picks the localization for a flow, 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

When Adapty looks for the localization that matches a user’s locale, the following happens:

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 flow’s default locale

This way 'pt_BR', pt-BR, and pt-br all resolve to the same 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.

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 argument of AdaptyUI.getFlowConfiguration. The argument is optional — omit it and the flow renders in en, or in its default locale when the flow has no en localization. When you request a localization the flow doesn’t have, the view falls back to the flow default without an error, and any strings the chosen localization lacks come from the default one.

Rendering in en by default requires Android SDK 4.0.1. In 4.0.0, omitting locale renders the flow’s default localization.
Custom (remote config) paywalls: getFlow returns every configured localization in flow.remoteConfigs. Each entry has a locale code and the config content (jsonString, or the parsed dataMap). Select the entry that matches the user, with your own fallback:

Adapty.getFlow("YOUR_PLACEMENT_ID") { result ->
    when (result) {
        is AdaptyResult.Success -> {
            val flow = result.value
            val config = flow.remoteConfigs.firstOrNull { it.locale == "en" }
                ?: flow.remoteConfigs.firstOrNull()
            // read your values from config?.dataMap
        }
        is AdaptyResult.Error -> {
            // handle the error
        }
    }
}

The locale code matching rules above describe how Adapty normalizes the locale codes stored on each remote config.

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 the localized string files in your project. If that’s the case, we recommend placing some key-value with the intended Adapty locale code in each of your files for the corresponding localizations. And then extract the value for this key when calling our SDK, like so:

// 1. Modify your strings.xml files

/*
strings.xml - Spanish
*/
<string name="adapty_paywalls_locale">es</string>

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

// 2. Extract and use the locale code

val localeCode = context.getString(R.string.adapty_paywalls_locale)
// pass locale code to AdaptyUI.getViewConfiguration or Adapty.getPaywall method

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

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 from some other objects that your platform provides, like this:

val locale = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N)
    context.resources.configuration.locales[0]
else
    context.resources.configuration.locale

val localeCode = locale.toLanguageTag()
// pass locale code to AdaptyUI.getViewConfiguration or Adapty.getPaywall method

Note that we don’t recommend this approach because it’s hard to predict what exactly will Adapty’s server get.

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