Использование локализаций и кодов локалей в Android SDK

Почему это важно

Коды локали используются, когда Adapty выбирает локализацию для флоу и когда вы читаете Remote Config для кастомного пейвола.

Коды локали бывают сложными и могут отличаться от платформы к платформе, поэтому Adapty использует единый внутренний стандарт для всех поддерживаемых платформ. Понимание этого стандарта поможет вам предсказать, какую локализацию получит пользователь.

Стандарт кодов локали в Adapty

Для кодов локали Adapty использует слегка модифицированный стандарт BCP 47: каждый код состоит из подтегов в нижнем регистре, разделённых дефисами. Примеры: en (английский), pt-br (португальский (Бразилия)), zh (упрощённый китайский), zh-hant (традиционный китайский).

Сопоставление кодов локалей

Когда Adapty ищет локализацию, соответствующую локали пользователя, происходит следующее:

1. Строка локали приводится к нижнему регистру, а все подчёркивания (_) заменяются дефисами (-)
2. Adapty ищет локализацию с полностью совпадающим кодом локали
3. Если совпадение не найдено, Adapty берёт подстроку до первого дефиса (pt для pt-br) и ищет соответствующую локализацию
4. Если совпадение снова не найдено, Adapty возвращает контент для локали флоу по умолчанию

Таким образом, 'pt_BR', pt-BR и pt-br — все они разрешаются в одну и ту же локализацию.

Реализация локализаций

В SDK v4 вы не передаёте код локали при получении флоу — getFlow возвращает флоу со всеми его локализациями.

• Флоу, собранные в билдере: SDK не считывает локаль устройства, поэтому определите её в своём приложении и передайте как аргумент locale в AdaptyUI.getFlowConfiguration. Аргумент необязательный — если его не передать, флоу отобразится на en или в локали по умолчанию, если у флоу нет локализации en. Если запросить локализацию, которой у флоу нет, отображение откатится к локали по умолчанию без ошибки, а строки, отсутствующие в выбранной локализации, будут взяты из локали по умолчанию.

Рендеринг с параметром en по умолчанию требует Android SDK 4.0.1. В версии 4.0.0 отсутствие locale отображает локализацию по умолчанию для флоу.

• Кастомные (Remote Config) пейволы: getFlow возвращает все настроенные локализации в flow.remoteConfigs. Каждая запись содержит код locale и содержимое конфига (jsonString или распарсенный dataMap). Выберите запись, соответствующую пользователю, реализовав собственный фолбэк:

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
        }
    }
}

Правила сопоставления кода локали выше описывают, как Adapty нормализует коды locale, хранящиеся в каждом Remote Config.

Почему это важно

Есть несколько сценариев, когда в игру вступают коды локалей — например, когда нужно получить правильный пейвол для текущей локализации приложения.

Поскольку коды локалей устроены сложно и могут различаться от платформы к платформе, мы опираемся на внутренний стандарт для всех поддерживаемых платформ. Но именно из-за этой сложности важно чётко понимать, что именно вы отправляете на наш сервер для получения нужной локализации и что происходит дальше — чтобы вы всегда получали именно то, что ожидаете.

Стандарт кодов локалей в Adapty

Для кодов локалей Adapty использует немного изменённый стандарт BCP 47: каждый код состоит из подтегов в нижнем регистре, разделённых дефисами. Примеры: en (английский), pt-br (португальский (Бразилия)), zh (упрощённый китайский), zh-hant (традиционный китайский).

Сопоставление кода локали

Когда Adapty получает вызов от клиентского SDK с кодом локали и начинает искать соответствующую локализацию пейвола, происходит следующее:

1. Входящая строка локали приводится к нижнему регистру, а все символы подчёркивания (_) заменяются дефисами (-)
2. Затем выполняется поиск локализации с полностью совпадающим кодом локали
3. Если совпадение не найдено, берётся подстрока до первого дефиса (pt для pt-br) и выполняется поиск соответствующей локализации
4. Если совпадение снова не найдено, возвращается контент для локали по умолчанию данного пейвола

Таким образом устройство iOS, отправившее 'pt_BR', устройство Android, отправившее pt-BR, и другое устройство, отправившее pt-br, получат одинаковый результат.

Рекомендуемый способ реализации локализаций

Если вас интересуют локализации, скорее всего, вы уже работаете с файлами локализованных строк в своём проекте. В таком случае мы рекомендуем добавить в каждый из этих файлов пару ключ-значение с нужным кодом локали Adapty для соответствующей локализации, а затем извлекать значение по этому ключу при вызове нашего SDK:

// 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

Это позволяет полностью контролировать, какая локализация будет загружена для каждого пользователя вашего приложения.

Альтернативный способ реализации локализаций

Похожего (но не идентичного) результата можно добиться без явного определения кодов локали для каждой локализации. Для этого можно извлечь код локали из других объектов, предоставляемых платформой:

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

Обратите внимание, что мы не рекомендуем этот подход, поскольку сложно предсказать, что именно получит сервер Adapty.

Если вы всё же решили использовать этот подход — убедитесь, что охватили все соответствующие сценарии.