Utiliser les localisations et les codes de langue dans le SDK React Native

Pourquoi c’est important

Les codes de langue entrent en jeu lorsqu’Adapty sélectionne la localisation d’un flow ou d’un onboarding, et lorsque vous lisez un Remote Config pour un paywall personnalisé.

Les codes de langue sont complexes et peuvent varier d’une plateforme à l’autre. C’est pourquoi Adapty s’appuie sur un standard interne unique pour toutes les plateformes qu’il prend en charge. Comprendre ce standard vous aide à anticiper quelle localisation un utilisateur recevra.

Standard des codes de langue chez Adapty

Pour les codes de langue, Adapty utilise une version légèrement modifiée du standard BCP 47 : chaque code est composé de sous-balises en minuscules, séparées par des traits d’union. Quelques exemples : en (anglais), pt-br (portugais (Brésil)), zh (chinois simplifié), zh-hant (chinois traditionnel).

Correspondance des codes de langue

Dans le SDK v4, les flows et les onboardings établissent la correspondance des codes de langue différemment : les flows sont localisés par le SDK sur l’appareil, les onboardings par le serveur Adapty.

Flows et paywalls Paywall Builder

Un paywall créé dans le Paywall Builder est livré en tant que flow dans le SDK v4, donc la règle ci-dessous couvre les deux.

La correspondance est exacte. Le SDK compare le code que vous transmettez avec les codes de localisation du flow caractère par caractère : il ne change pas la casse, ne remplace pas les underscores (_) par des tirets (-), et ne revient pas au sous-tag de langue. Pour un flow avec une localisation pt-br, seul pt-br correspond : pt-BR, pt_BR et pt-PT ne correspondent pas.

Lorsque le code ne correspond à aucune localisation, le flow s’affiche silencieusement dans sa locale par défaut — le SDK ne renvoie pas d’erreur et n’enregistre pas d’avertissement.

Lorsque le code correspond, Adapty fusionne la localisation avec la locale par défaut : les chaînes et assets que la localisation correspondante ne définit pas sont repris depuis la localisation par défaut.

Omettre le code de langue ne revient pas à demander la localisation par défaut du flow : le SDK substitue un en fixe. Un flow dont la langue par défaut est de s’affiche quand même en en s’il possède une localisation en, et ne bascule sur de que si ce n’est pas le cas.

Onboardings

Les onboardings sont localisés côté serveur, et les règles du serveur acceptent d’autres formats. Lorsque vous passez un locale à getOnboarding :

1. La chaîne de locale est convertie en minuscules et tous les underscores (_) sont remplacés par des tirets (-)
2. Adapty recherche la localisation dont le code de locale correspond exactement
3. Si aucune correspondance n’est trouvée, Adapty extrait la sous-chaîne avant le premier tiret (pt pour pt-br) et recherche la localisation correspondante
4. Si aucune correspondance n’est trouvée non plus, Adapty renvoie le contenu pour la locale par défaut de l’onboarding

Cette façon de faire, pt_BR, pt-BR et pt-br renvoient tous au même onboarding localisé.

Implémentation des localisations

Dans le SDK v4, vous ne passez pas de code de langue lors de la récupération d’un flow — getFlow retourne le flow avec toutes ses localisations, et Adapty en applique une lors de la construction de la vue du flow.

• Flows créés dans le builder : le SDK ne lit pas la langue de l’appareil, donc résolvez-la dans votre application et passez-la via le paramètre locale de createFlowView, ou dans la prop params du composant AdaptyFlowView embarqué. Ce paramètre est optionnel — omettez-le et le flow s’affiche en en, ou dans sa langue par défaut si le flow n’a pas de localisation en.

  import { createFlowView } from 'react-native-adapty';
  
  const view = await createFlowView(flow, { locale: 'es' });

view.locale indique la localisation avec laquelle la vue a été réellement construite — le paramètre régional que vous avez demandé si cette localisation existe, ou la localisation par défaut du flow sinon. Le paramètre locale et view.locale nécessitent tous les deux le SDK React Native 4.0.2 ou une version ultérieure ; view.locale est undefined sur les versions antérieures.

Le composant AdaptyFlowView intégré crée sa propre vue, il n’y a donc rien depuis lequel votre code peut lire locale. Récupérez la localisation depuis l’objet que reçoit son gestionnaire onAppeared :

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

L’argument onAppeared nécessite le SDK React Native 4.0.3 ou version ultérieure.

• Paywalls personnalisés (Remote Config) : getFlow retourne toutes les localisations configurées dans flow.remoteConfigs. Chaque entrée possède un code lang et un objet data. Sélectionnez l’entrée correspondant à l’utilisateur, avec votre propre fallback :

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 stocke ces codes lang dans le format décrit dans Standard des codes de langue dans Adapty. Le SDK ne fait pas correspondre les Remote Configs à une locale, c’est donc à votre application de choisir quelle entrée utiliser.

Pourquoi c’est important

Les codes de langue entrent en jeu dans plusieurs situations — par exemple, lorsque vous souhaitez récupérer le bon paywall pour la localisation actuelle de votre application.

Les codes de langue sont complexes et peuvent varier d’une plateforme à l’autre. Nous nous appuyons donc sur un standard interne commun à toutes les plateformes que nous supportons. Cela dit, justement parce que ces codes sont complexes, il est vraiment important que vous compreniez exactement ce que vous envoyez à notre serveur pour obtenir la bonne localisation, et ce qui se passe ensuite — afin de toujours recevoir ce que vous attendez.

Standard des codes de langue chez Adapty

Pour les codes de langue, Adapty utilise une version légèrement modifiée du standard BCP 47 : chaque code est composé de sous-balises en minuscules, séparées par des tirets. Quelques exemples : en (anglais), pt-br (portugais (Brésil)), zh (chinois simplifié), zh-hant (chinois traditionnel).

Correspondance des codes de langue

Lorsqu’Adapty reçoit un appel du SDK côté client avec le code de langue et commence à rechercher la localisation correspondante d’un paywall, voici ce qui se passe :

1. La chaîne de langue reçue est convertie en minuscules et tous les underscores (_) sont remplacés par des tirets (-)
2. On recherche ensuite la localisation dont le code de langue correspond exactement
3. Si aucune correspondance n’est trouvée, on extrait la sous-chaîne avant le premier tiret (pt pour pt-br) et on cherche la localisation correspondante
4. Si aucune correspondance n’est encore trouvée, on renvoie le contenu dans la langue par défaut du paywall

De cette façon, un appareil iOS qui a envoyé 'pt_BR', un appareil Android qui a envoyé pt-BR, et un autre appareil qui a envoyé pt-br obtiendront le même résultat.

Mise en œuvre des localisations : méthode recommandée

Si vous vous interrogez sur les localisations, il y a de bonnes chances que vous gériez déjà des fichiers de chaînes localisées dans votre projet. Dans ce cas, nous recommandons d’ajouter une paire clé-valeur avec le code de locale Adapty correspondant dans chacun de vos fichiers de localisation. Extrayez ensuite la valeur de cette clé lors de l’appel à notre SDK, comme ceci :

// 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);
  };
};

C’est ainsi que vous vous assurez d’avoir un contrôle total sur la localisation qui sera récupérée pour chaque utilisateur de votre application.

Implémenter les localisations : l’autre approche

Vous pouvez obtenir des résultats similaires (mais pas identiques) sans définir explicitement les codes de langue pour chaque localisation. Cela implique d’extraire un code de langue depuis l’appareil, par exemple via 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);
};

Notez que nous ne recommandons pas cette approche pour plusieurs raisons :

1. Sur iOS, les langues préférées et la locale régionale actuelle ne sont pas identiques. Pour que la localisation soit correctement sélectionnée, vous devrez soit vous appuyer sur la logique de résolution d’Apple — qui fonctionne nativement avec l’approche recommandée utilisant des fichiers de chaînes localisées — soit la recréer vous-même.
2. La locale de l’appareil peut ne correspondre à aucune localisation configurée dans Adapty. Dans ce cas, le SDK utilise en priorité une correspondance sur le premier sous-tag ou, en dernier recours, en — ce qui n’est peut-être pas la langue par défaut souhaitée pour cet utilisateur.

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