Utiliser les localisations et les codes de langue dans le SDK Capacitor

Pourquoi c’est important

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

Les codes de locale sont complexes et peuvent varier d’une plateforme à l’autre. Adapty s’appuie donc sur un standard interne unique, commun à toutes les plateformes qu’il prend en charge. Comprendre ce standard vous permet d’anticiper quelle localisation reçoit un utilisateur.

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

Dans le SDK v4, les flows et les onboardings font correspondre les 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é sous forme de flow dans le SDK v4, donc la règle ci-dessous s’applique aux 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 modifie pas la casse, ne remplace pas les tirets bas (_) par des tirets (-), et ne se replie pas sur le 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 localisation par défaut : les chaînes et les ressources que la localisation correspondante ne définit pas sont reprises depuis la localisation par défaut.

Omettre le code de langue n’est pas la même chose que demander la localisation par défaut du flow : le SDK utilise 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 vers de que s’il n’en a pas.

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 retourne le contenu dans la locale par défaut de l’onboarding

Cette approche permet à pt_BR, pt-BR et pt-br de tous pointer vers la même localisation d’onboarding.

Implémenter les localisations

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

• Flows construits dans le builder : le SDK ne lit pas la langue du système, vous devez donc la résoudre dans votre app et la passer comme option locale de createFlowView. C’est optionnel — omettez-la et le flow s’affiche en en, ou dans sa langue par défaut si le flow ne possède pas de localisation en.

  import { createFlowView } from '@adapty/capacitor';
  
  const view = await createFlowView(flow, { locale: 'es' });

view.locale indique la localisation avec laquelle la vue a été construite. L’option locale et view.locale nécessitent le SDK Capacitor 4.0.1-beta.1, et view.locale est undefined sur les versions antérieures. Le gestionnaire onAppeared rapporte la même valeur.

• Paywalls personnalisés (Remote Config) : getFlow renvoie 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 qui correspond à l’utilisateur, avec votre propre solution de repli :

const flow = await adapty.getFlow({ placementId: '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 locale dans Adapty. Le SDK ne fait pas correspondre les Remote Configs à une locale, c’est donc à votre application de choisir quelle entrée appliquer.

Pourquoi c’est important

Il existe quelques scénarios où les codes de locale entrent en jeu — par exemple, lorsque vous essayez de récupérer le bon paywall pour la localisation actuelle de votre application.

Les codes de locale étant complexes et pouvant varier d’une plateforme à l’autre, nous nous appuyons sur un standard interne pour toutes les plateformes que nous supportons. Cependant, en raison de cette complexité, 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 que vous receviez toujours 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-tags en minuscules, séparés 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 client avec un code de langue et commence à chercher la localisation correspondante d’un paywall, voici ce qui se passe :

1. La chaîne de locale 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 locale 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 trouvée non plus, on renvoie le contenu dans la locale 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.

Implémentation des localisations : méthode recommandée

Si vous vous interrogez sur les localisations, il y a de grandes chances que vous gériez déjà des fichiers de chaînes localisées dans votre projet. Dans ce cas, nous vous recommandons d’ajouter une paire clé-valeur avec le code de locale Adapty correspondant dans chacun de vos fichiers de localisation. Récupérez ensuite la valeur de cette clé lors de l’appel au 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);
  };
};

De cette façon, vous êtes totalement maître de la localisation qui sera récupérée pour chaque utilisateur de votre application.

Implémenter les localisations : une autre approche

Vous pouvez obtenir des résultats similaires (mais non identiques) sans définir explicitement de codes de langue pour chaque localisation. Il s’agit d’extraire un code de langue depuis d’autres objets fournis par votre plateforme, comme ceci :

const getLocaleCode = () => {
  if (Capacitor.getPlatform() === 'ios') {
    return navigator.language || 'en';
  } else {
    return navigator.language || 'en';
  }
};

const fetchPaywall = async () => {
  const locale = getLocaleCode();
  // pass locale code to adapty.getPaywall or adapty.getPaywallForDefaultAudience method
  const paywall = await adapty.getPaywallForDefaultAudience('placement_id', locale);
};

Notez que nous déconseillons cette approche pour plusieurs raisons :

1. Sur iOS, les langues préférées et la locale actuelle ne sont pas identiques. Si vous voulez que la localisation soit sélectionnée correctement, vous devrez soit vous reposer sur la logique d’Apple, qui fonctionne directement si vous utilisez l’approche recommandée avec des fichiers de chaînes localisées, soit la recréer vous-même.
2. Il est difficile de prédire ce que le serveur d’Adapty recevra exactement. Par exemple, sur iOS, il est possible d’obtenir une locale comme ar_OM@numbers='latn' sur un appareil et de l’envoyer à notre serveur. Pour cet appel, vous obtiendrez non pas la localisation ar-om que vous cherchiez, mais ar, ce qui est probablement inattendu.

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