Utiliser les localisations et codes de locale dans le SDK Android

Pourquoi c’est important

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

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

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-étiquettes 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 gèrent 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 créés avec le 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 la balise 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 ne consigne 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 proviennent de 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 dispose d’une localisation en, et ne bascule sur de que dans le cas contraire. Cela s’applique au SDK Android 4.0.1 et ultérieur — en 4.0.0, omettre le code affiche la localisation par défaut du flow.

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 locale est convertie en minuscules et tous les underscores (_) sont remplacés par des tirets (-)
2. Adapty recherche la localisation dont le code correspond exactement à la locale
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 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émentation des localisations

Dans le SDK v4, vous ne transmettez pas de code de langue lors de la récupération d’un flow — getFlow retourne le flow avec toutes ses localisations.

• Flows créés dans le builder : le SDK ne lit pas les paramètres régionaux de l’appareil, donc résolvez-les dans votre application et transmettez-les via l’argument locale de AdaptyUI.getFlowConfiguration. Cet argument est optionnel — omettez-le et le flow s’affiche en en, ou dans sa langue par défaut si le flow ne possède pas de localisation en.
• Paywalls personnalisés (Remote Config) : getFlow renvoie toutes les localisations configurées dans flow.remoteConfigs. Chaque entrée contient un code locale et le contenu de la configuration (jsonString, ou le dataMap analysé). Sélectionnez l’entrée qui correspond à l’utilisateur, avec votre propre mécanisme de repli :

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 stocke ces codes locale 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 décider quelle entrée appliquer.

Pourquoi c’est important

Il existe plusieurs situations où les codes de langue 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 langue étant complexes et pouvant varier d’une plateforme à l’autre, nous nous appuyons sur un standard interne pour toutes les plateformes que nous prenons en charge. 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 de code 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

Quand Adapty reçoit un appel du SDK côté 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 cherche 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

Ainsi, 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, vous travaillez probablement déjà avec 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. Ensuite, récupérez la valeur de cette clé lors de l’appel à notre SDK, comme ceci :

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

Vous contrôlez ainsi entièrement la localisation qui sera récupérée pour chaque utilisateur de votre application.

Implémenter les localisations : l’autre méthode

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

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

Notez que nous ne recommandons pas cette approche car il est difficile de prévoir exactement ce que le serveur d’Adapty recevra.

Si vous décidez tout de même d’utiliser cette approche, assurez-vous d’avoir couvert tous les cas d’utilisation pertinents.