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

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

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

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

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

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

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

В SDK v4 флоу и онбординги сопоставляют коды локалей по-разному: флоу локализуются SDK на устройстве, онбординги — на сервере Adapty.

Флоу и пейволы

Пейвол, который рендерит Adapty, в SDK v4 доставляется как флоу, поэтому приведённое ниже правило распространяется на оба случая.

Совпадение точное. SDK сравнивает переданный вами код с кодами локализации флоу посимвольно: не меняет регистр, не заменяет подчёркивания (_) на дефисы (-) и не откатывается к языковому подтегу. Для флоу с локализацией pt-br подходит только pt-br: pt-BR, pt_BR и pt-PT — не совпадут.

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

Если код совпадает, Adapty объединяет найденную локализацию с локализацией по умолчанию: строки и ресурсы, не определённые в найденной локализации, берутся из локализации по умолчанию.

Пропуск кода локали — это не то же самое, что запрос локализации флоу по умолчанию: SDK подставляет фиксированный en. Флоу, у которого локаль по умолчанию — de, всё равно отображается на en, если у него есть локализация en, и только при её отсутствии переключается на de.

Warning

Передавайте код локали точно так, как он настроен в дашборде — строчные подтеги, разделённые дефисами. Не передавайте идентификатор локали устройства напрямую: getLocales()[0].languageTag из react-native-localize возвращает pt-BR, и это приведёт к использованию локализации по умолчанию. Преобразуйте значение в своём приложении перед передачей.

Онбординги

Онбординги локализуются на стороне сервера, и правила сервера допускают другие форматы. Когда вы передаёте locale в getOnboarding:

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

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

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

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

Флоу, созданные в билдере: SDK не считывает локаль устройства, поэтому определите её в своём приложении и передайте как параметр locale в createFlowView или через проп params встроенного компонента AdaptyFlowView. Это необязательно — без него флоу отображается на en или на локали по умолчанию, если локализации en нет.
```
import { createFlowView } from 'react-native-adapty';

const view = await createFlowView(flow, { locale: 'es' });
```

view.locale сообщает локализацию, с которой было фактически построено представление: запрошенную вами локаль, если такая локализация существует, или локаль по умолчанию для флоу в противном случае. Параметр locale и view.locale требуют React Native SDK 4.0.2 или новее; на более ранних версиях view.locale равно undefined.

Встроенный компонент AdaptyFlowView создаёт собственное представление, поэтому считать locale напрямую из него не получится. Вместо этого получайте локализацию из объекта, который принимает обработчик onAppeared:

  <AdaptyFlowView
    flow={flow}
    params={{ locale: 'es' }}
    onAppeared={(view) => setScreenLocale(view.locale)}
  />

Аргумент onAppeared требует React Native SDK версии 4.0.3 или выше.

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


const flow = await adapty.getFlow('placement_id');
const config = flow.remoteConfigs?.find((c) => c.lang === 'en') ?? flow.remoteConfigs?.[0];
// read your values from config?.data

Adapty хранит эти коды lang в формате, описанном в разделе Стандарт кодов локалей в Adapty. SDK не сопоставляет Remote Config с локалью автоматически — выбор нужной записи остаётся за вашим приложением.

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

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

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

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

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

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

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

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

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

Реализация локализаций: рекомендуемый подход

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

// 1. Modify your localization files (e.g., using react-i18next)

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

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

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

// 2. Extract and use the locale code

const MyComponent = () => {
  const { t } = useTranslation();
  
  const fetchPaywall = async () => {
    const locale = t('adapty_paywalls_locale');
    // pass locale code to adapty.getPaywall or adapty.getPaywallForDefaultAudience method
    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);
};

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

На iOS предпочитаемые языки и текущая региональная локаль — это не одно и то же. Чтобы локализация определялась корректно, нужно либо положиться на логику Apple — она работает из коробки при рекомендуемом подходе с локализованными строковыми файлами — либо реализовать аналогичную логику самостоятельно.
Локаль устройства может не совпадать ни с одной из локализаций, настроенных в Adapty. В таком случае SDK откатывается к совпадению по первому субтегу или, в крайнем случае, к en — что может оказаться не тем языком, который вы хотели бы показать этому пользователю по умолчанию.

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