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

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

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

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

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

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

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

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

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

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

// 1. Измените файлы локализации (например, используя react-i18next)

/*
en.json
*/
{
  "adapty_paywalls_locale": "en"
}

/*
es.json
*/
{
  "adapty_paywalls_locale": "es"
}

/*
pt-BR.json
*/
{
  "adapty_paywalls_locale": "pt-br"
}

// 2. Извлеките и используйте код локали

const MyComponent = () => {
  const { t } = useTranslation();
  
  const fetchPaywall = async () => {
    const locale = t('adapty_paywalls_locale');
    // передайте код локали в метод adapty.getPaywall или adapty.getPaywallForDefaultAudience
    const paywall = await adapty.getPaywallForDefaultAudience('placement_id', locale);
  };
};

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

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

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


const fetchPaywall = async () => {
  // getLocales() returns the user's preferred locales in BCP-47 format (e.g., 'en-US', 'pt-BR')
  const locale = RNLocalize.getLocales()[0].languageTag;
  // pass locale code to adapty.getPaywall or adapty.getPaywallForDefaultAudience method
  const paywall = await adapty.getPaywallForDefaultAudience('placement_id', locale);
};

Обратите внимание, что мы не рекомендуем этот подход по ряду причин:

  1. На iOS предпочтительные языки и текущая региональная локаль — не одно и то же. Чтобы локализация выбиралась корректно, придётся либо опираться на логику разрешения Apple — которая работает автоматически при рекомендуемом подходе с локализованными строковыми файлами — либо воспроизводить её самостоятельно.
  2. Локаль устройства может не совпадать ни с одной из локализаций, настроенных в Adapty. В таком случае SDK сначала попытается найти совпадение по первому подтегу, а если не найдёт — вернётся к en, который может оказаться не тем языком, который вы хотите показывать этому пользователю по умолчанию. Should you decide to use this approach anyway — make sure you’ve covered all the relevant use cases.