Utiliser les localisations et codes de langue dans le SDK iOS

Pourquoi c’est important

Les codes de langue entrent en jeu lorsqu’Adapty choisit la localisation d’un flow 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 permet de prévoir 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

Lorsqu’Adapty recherche la localisation correspondant à la locale d’un utilisateur, voici ce qui se passe :

La chaîne de locale est convertie en minuscules et tous les tirets bas (_) sont remplacés par des tirets (-)
Adapty recherche la localisation dont le code de locale correspond exactement
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
Si aucune correspondance n’est trouvée à nouveau, Adapty retourne le contenu dans la locale par défaut du flow

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

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 l’ensemble de ses localisations.

Flows créés dans le builder : le SDK ne lit pas la locale de l’appareil, vous devez donc la résoudre dans votre application et la passer à AdaptyUI.getFlowConfiguration(forFlow:locale:). Ce paramètre est optionnel — omettez-le et le flow s’affiche en en, ou dans sa locale par défaut si le flow n’a 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 dictionary analysé). Sélectionnez l’entrée qui correspond à l’utilisateur, avec votre propre logique de secours :

do {
    let flow = try await Adapty.getFlow(placementId: "YOUR_PLACEMENT_ID")
    let config = flow.remoteConfigs.first(where: { $0.locale == "en" })
        ?? flow.remoteConfigs.first
    // read your values from config?.dictionary
} catch {
    // handle the error
}

Les règles de correspondance des codes de langue décrites ci-dessus expliquent comment Adapty normalise les codes locale stockés dans chaque Remote Config.

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 supportons. Cependant, en raison de cette complexité, il est vraiment important de comprendre 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

Correspondance des codes de langue

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

La chaîne de locale reçue est convertie en minuscules et tous les underscores (_) sont remplacés par des tirets (-)
On recherche ensuite la localisation dont le code de locale correspond exactement
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
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.

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

Si vous vous posez des questions sur les localisations, il y a de grandes chances que vous travailliez déjà avec 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 souhaité dans chacun de vos fichiers pour les localisations correspondantes. Extrayez ensuite la valeur de cette clé lors de l’appel à notre SDK, comme ceci :

// 1. Modify your Localizable.strings files

/*
Localizable.strings - Spanish
*/
adapty_paywalls_locale = "es";
/*
Localizable.strings - Portuguese (Brazil)
*/
adapty_paywalls_locale = "pt-br";
// 2. Extract and use the locale code
let locale = NSLocalizedString("adapty_paywalls_locale", comment: "")
// pass locale code to AdaptyUI.getViewConfiguration or Adapty.getPaywall method

Ainsi, vous gardez 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 façon

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

let locale = Locale.current.identifier
// pass locale code to AdaptyUI.getViewConfiguration or Adapty.getPaywall method

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

Sur iOS, les langues préférées et la locale actuelle ne sont pas identiques. Pour que la localisation soit correctement sélectionnée, vous devrez soit vous appuyer sur la logique d’Apple, qui fonctionne automatiquement si vous utilisez l’approche recommandée avec des fichiers de chaînes localisées, soit la recréer vous-même.
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. Dans ce cas, vous obtiendrez non pas la localisation ar-om que vous recherchiez, mais plutôt ar, ce qui est probablement inattendu.

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