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

Pourquoi c’est important

Les codes de langue entrent en jeu lorsqu’Adapty sélectionne la localisation pour un flow ou 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 permet de prédire quelle localisation sera reçue par 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 conçu dans le Paywall Builder est livré sous forme de 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 modifie pas la casse, ne remplace pas les underscores (_) 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 retourne pas d’erreur et ne journalise pas d’avertissement.

Lorsque le code correspond, Adapty fusionne la localisation avec la localisation par défaut : les chaînes et ressources que la localisation correspondante ne définit pas sont héritées 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 revient à de qu’en l’absence de celle-ci.

Passez le code de langue exactement tel qu’il est configuré dans le tableau de bord — sous-balises en minuscules séparées par des tirets. Ne passez pas directement un identifiant de locale système : CultureInfo.CurrentCulture.Name retourne pt-BR, ce qui entraîne un repli vers la localisation par défaut. Convertissez la valeur dans votre application avant de la transmettre.

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 :

La chaîne locale est convertie en minuscules et tous les underscores (_) sont remplacés par des tirets (-)
Adapty recherche la localisation dont le code 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 non plus, Adapty retourne le contenu dans la langue par défaut de l’onboarding

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

Implémentation des localisations

Avec le SDK v4, vous ne transmettez pas de code de langue lors de la récupération d’un flow — le flow est localisé au moment de la création de sa vue.

Paywalls Flow Builder et Paywall Builder : le SDK ne lit pas les paramètres régionaux de l’appareil, résolvez-les dans votre application et transmettez-les lors de la création de la vue. Le code de locale est facultatif — omettez-le et le flow s’affiche en en, ou dans sa locale par défaut si le flow ne possède pas de localisation en.
Paywalls personnalisés (Remote Config) : GetFlow retourne toutes les localisations configurées dans flow.RemoteConfigs. Chaque entrée est un AdaptyRemoteConfig avec un code Locale et un Dictionary de valeurs. Sélectionnez l’entrée correspondant à l’utilisateur, avec votre propre fallback :

using System.Linq;
using AdaptySDK;

Adapty.GetFlow("YOUR_PLACEMENT_ID", (flow, error) => {
    if (error != null) {
        // handle the error
        return;
    }

    var config = flow.RemoteConfigs.FirstOrDefault(c => c.Locale == "en")
        ?? flow.RemoteConfigs.FirstOrDefault();
    // read your values from config?.Dictionary
});

Adapty stocke ces codes Locale dans le format décrit dans Standard de code de locale chez Adapty. Le SDK ne fait pas correspondre les Remote Configs à une locale, c’est donc à votre application de déterminer quelle entrée appliquer.

Choisir la localisation d’un flow

Pour afficher un flow ou un paywall avec une localisation spécifique, passez le code de langue à SetLocale lors de la création de la vue :

var parameters = new AdaptyUICreateFlowViewParameters()
    .SetLocale("pt-br");

AdaptyUI.CreateFlowView(flow, parameters, (view, error) => {
    if (error != null) {
        // handle the error
        return;
    }

    // view.Locale — the localization the view was built with
});

La vue rapporte la localisation avec laquelle elle a été effectivement construite dans view.Locale : celle que vous avez demandée si cette localisation existe, ou la localisation par défaut du flow dans le cas contraire.

Pourquoi c’est important

Les codes de langue entrent en jeu dans plusieurs scénarios — par exemple, quand vous cherchez à récupérer le bon paywall selon 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 une norme interne pour toutes les plateformes que nous supportons. Cependant, étant donné cette complexité, il est essentiel 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

Correspondance des codes de langue

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

La chaîne de langue reçue est convertie en minuscules et tous les underscores (_) sont remplacés par des tirets (-)
Nous cherchons ensuite la localisation dont le code de langue correspond exactement
Si aucune correspondance n’est trouvée, nous extrayons la sous-chaîne avant le premier tiret (pt pour pt-br) et cherchons la localisation correspondante
Si aucune correspondance n’est encore trouvée, nous renvoyons le contenu dans la langue par défaut du paywall

Ainsi, un appareil iOS ayant envoyé 'pt_BR', un appareil Android ayant envoyé pt-BR, et un autre appareil ayant envoyé pt-br obtiendront le même résultat.

Mise en œuvre des localisations : approche recommandée

Si vous vous posez des questions sur les localisations, vous utilisez probablement 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 pour les localisations concernées. Ensuite, récupérez la valeur de cette clé lors de l’appel de notre SDK, comme ceci :

// 1. Modify your localization files (e.g., using Unity's Localization package)

/*
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
using UnityEngine;
using UnityEngine.Localization;
using UnityEngine.Localization.Settings;
using AdaptySDK;

public class PaywallManager : MonoBehaviour
{
    public async void FetchPaywall()
    {
        // Get the current locale from Unity's Localization system
        var locale = LocalizationSettings.SelectedLocale;
        var localeCode = GetAdaptyLocaleCode(locale);
        
        // Pass locale code to Adapty.GetPaywall or Adapty.GetPaywallForDefaultAudience method
        Adapty.GetPaywall("placement_id", localeCode, (paywall, error) => {
            if (error != null) {
                // handle the error
                return;
            }
            // Use the paywall
        });
    }
    
    private string GetAdaptyLocaleCode(Locale locale)
    {
        // Convert Unity locale to Adapty format
        var localeIdentifier = locale.Identifier.Code;
        return localeIdentifier.ToLower().Replace('_', '-');
    }
}

De cette façon, vous pouvez vous assurer de contrôler entièrement quelle localisation 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 locale pour chaque localisation. Il s’agit d’extraire un code de locale depuis d’autres objets fournis par votre plateforme, comme ceci :

using UnityEngine;
using System.Globalization;
using AdaptySDK;

public class PaywallManager : MonoBehaviour
{
    public void FetchPaywall()
    {
        var localeCode = GetSystemLocaleCode();
        
        // Pass locale code to Adapty.GetPaywall or Adapty.GetPaywallForDefaultAudience method
        Adapty.GetPaywall("placement_id", localeCode, (paywall, error) => {
            if (error != null) {
                // handle the error
                return;
            }
            // Use the paywall
        });
    }
    
    private string GetSystemLocaleCode()
    {
        // Get the system's current culture
        var culture = CultureInfo.CurrentCulture;
        var languageCode = culture.TwoLetterISOLanguageName;
        var regionCode = culture.Name.Contains('-') ? culture.Name.Split('-')[1] : null;
        
        if (!string.IsNullOrEmpty(regionCode))
        {
            return $"{languageCode}-{regionCode.ToLower()}";
        }
        
        return languageCode;
    }
}

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

Sur iOS, les langues préférées et la locale actuelle ne sont pas identiques. Si vous souhaitez que la localisation soit sélectionnée correctement, vous devrez soit vous appuyer sur la logique d’Apple, qui fonctionne telle quelle 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. Pour cet appel, 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.