Unity SDK'da yerelleştirmeleri ve yerel ayar kodlarını kullanın

Bu neden önemli

Locale kodları, Adapty bir flow veya onboarding için yerelleştirme seçerken ve özel bir paywall için remote config okurken devreye girer.

Locale kodları karmaşık olabilir ve platformdan platforma farklılık gösterebilir; bu nedenle Adapty, desteklediği her platformda tek bir iç standarda dayanır. Bu standardı anlamak, bir kullanıcının hangi yerelleştirmeyi alacağını tahmin etmenize yardımcı olur.

Adapty’de yerel ayar kodu standardı

Adapty, yerel ayar kodları için biraz değiştirilmiş bir BCP 47 standardı kullanır: her kod, kısa çizgilerle ayrılmış küçük harf alt etiketlerden oluşur. Bazı örnekler: en (İngilizce), pt-br (Portekizce (Brezilya)), zh (Basitleştirilmiş Çince), zh-hant (Geleneksel Çince).

Locale kod eşleştirme

SDK v4’te, flow’lar ve onboarding’ler locale kodlarını farklı şekilde eşleştirir: flow’lar cihazda SDK tarafından, onboarding’ler ise Adapty sunucusu tarafından yerelleştirilir.

Flow’lar ve Paywall Builder paywallları

Paywall Builder’da oluşturulan bir paywall, SDK v4’te flow olarak sunulur; dolayısıyla aşağıdaki kural her ikisi için de geçerlidir.

Eşleşme tam olarak yapılır. SDK, ilettiğiniz kodu flow’un yerelleştirme kodlarıyla karakter karakter karşılaştırır: büyük/küçük harf dönüşümü yapmaz, alt çizgileri (_) kısa çizgilerle (-) değiştirmez ve yalnızca dil alt etiketine geri dönmez. pt-br yerelleştirmesine sahip bir flow için yalnızca pt-br eşleşir: pt-BR, pt_BR ve pt-PT hiçbiri eşleşmez.

Kod hiçbir yerelleştirmeyle eşleşmediğinde, flow varsayılan locale’unda sessizce gösterilir — SDK hata döndürmez ve uyarı loglamaz.

Kod eşleştiğinde ise Adapty, eşleşen yerelleştirmeyi varsayılan olanla birleştirir: eşleşen yerelleştirmede tanımlanmayan string ve asset’ler varsayılan yerelleştirmeden alınır.

Yerel ayar kodunu atlamak, flow’un varsayılan yerelleştirmesini istemekle aynı şey değildir: SDK sabit olarak en kullanır. Varsayılan yerel ayarı de olan bir flow, en yerelleştirmesi varsa en dilinde görüntülenir; yalnızca en yerelleştirmesi yoksa de diline geri döner.

Yerel ayar kodunu tam olarak kontrol panelinde yapılandırıldığı şekilde geçirin — küçük harfli alt etiketler tire ile ayrılmış olarak. Sistem yerel ayar tanımlayıcısını olduğu gibi geçirmeyin: CultureInfo.CurrentCulture.Name ifadesi pt-BR döndürür ve bu varsayılan yerelleştirmeye geri döner. Değeri uygulamanızda dönüştürdükten sonra geçirin.

Onboarding’ler

Onboarding’ler sunucu tarafında yerelleştirilir ve sunucu kuralları diğer formatları da kabul eder. GetOnboarding fonksiyonuna bir Locale geçtiğinizde:

Locale dizesi küçük harfe dönüştürülür ve tüm alt çizgiler (_) kısa çizgiyle (-) değiştirilir
Adapty, tam olarak eşleşen locale koduyla yerelleştirmeyi arar
Eşleşme bulunamazsa, Adapty ilk kısa çizgiden önceki alt dizeyi (pt-br için pt) alır ve eşleşen yerelleştirmeyi arar
Yine eşleşme bulunamazsa, Adapty onboarding’in varsayılan locale’i için içeriği döndürür

Bu sayede pt_BR, pt-BR ve pt-br hepsi aynı onboarding yerelleştirmesine çözümlenir.

Yerelleştirmeleri uygulama

SDK v4’te flow çekerken bir locale kodu iletmezsiniz; flow’un görünümü oluşturulduğunda yerelleştirilir.

Flow Builder ve Paywall Builder paywallları: SDK cihaz dilini okumaz, bu yüzden bunu uygulamanızda çözümleyin ve view oluştururken iletin. Dil kodu isteğe bağlıdır — belirtmezseniz flow en dilinde veya flow’un en yerelleştirmesi yoksa varsayılan dilinde görüntülenir.
Özel (remote config) paywalllar: GetFlow, yapılandırılmış tüm yerelleştirmeleri flow.RemoteConfigs içinde döndürür. Her giriş, bir Locale kodu ve değerlerin yer aldığı bir Dictionary içeren AdaptyRemoteConfig nesnesidir. Kullanıcıyla eşleşen girişi kendi geri dönüş mantığınızla seçin:

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, Locale kodlarını Adapty’deki Locale kodu standardı bölümünde açıklanan biçimde saklar. SDK, remote config’leri bir locale ile eşleştirmez; dolayısıyla hangi girişin uygulanacağına uygulamanız karar verir.

Bir flow’un yerelleştirmesini seçme

Bir flow veya paywall’ı belirli bir yerelleştirmeyle oluşturmak için, görünümü oluştururken SetLocale metoduna locale kodunu geçin:

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

view.Locale ile görünüm, gerçekte hangi yerelleştirmeyle oluşturulduğunu raporlar: eğer istediğiniz yerelleştirme mevcutsa o yerelleştirmeyi, aksi takdirde flow’un varsayılan yerelleştirmesini kullanır.

Bu Neden Önemli

Locale kodlarının devreye girdiği birkaç senaryo vardır — örneğin, uygulamanızın mevcut yerelleştirmesi için doğru paywall’ı çekmeye çalışırken.

Locale kodları karmaşık olabilir ve platformdan platforma farklılık gösterebileceğinden, desteklediğimiz tüm platformlar için dahili bir standarda güveniyoruz. Ancak bu kodlar karmaşık olduğu için, doğru yerelleştirmeyi almak adına sunucumuza tam olarak ne gönderdiğinizi ve bundan sonra ne olduğunu anlamanız son derece önemlidir; böylece her zaman beklediğinizi alırsınız.

Adapty’de locale kodu standardı

Locale kodları için Adapty, hafifçe değiştirilmiş BCP 47 standardını kullanır: her kod, kısa çizgilerle ayrılmış küçük harfli alt etiketlerden oluşur. Bazı örnekler: en (İngilizce), pt-br (Portekizce (Brezilya)), zh (Basitleştirilmiş Çince), zh-hant (Geleneksel Çince).

Yerel ayar kodu eşleştirme

Adapty, istemci tarafı SDK’dan yerel ayar koduyla birlikte bir çağrı aldığında, paywall’a ait karşılıklı bir yerelleştirme aramaya başlar ve şu adımlar gerçekleşir:

Gelen yerel ayar dizesi küçük harfe dönüştürülür ve tüm alt çizgiler (_) kısa çizgiyle (-) değiştirilir
Ardından tam olarak eşleşen yerel ayar koduna sahip yerelleştirme aranır
Eşleşme bulunamazsa, ilk kısa çizgiden önceki alt dize alınır (pt-br için pt) ve eşleşen yerelleştirme aranır
Yine eşleşme bulunamazsa, paywall’un varsayılan yerel ayarındaki içerik döndürülür

Bu sayede 'pt_BR' gönderen bir iOS cihazı, pt-BR gönderen bir Android cihazı ve pt-br gönderen başka bir cihaz aynı sonucu alır.

Yerelleştirmeleri uygulama: önerilen yol

Yerelleştirmelerle ilgileniyorsanız, büyük ihtimalle projenizde zaten yerelleştirilmiş string dosyalarıyla çalışıyorsunuzdur. Bu durumda, her dosyanıza ilgili yerelleştirme için amaçlanan Adapty locale kodu ile birlikte bir anahtar-değer çifti eklemenizi öneririz. Ardından SDK’mızı çağırırken bu anahtarın değerini şu şekilde çıkarın:

// 1. Yerelleştirme dosyalarınızı düzenleyin (örneğin, Unity'nin Localization paketini kullanarak)

/*
en.json
*/
{
  "adapty_paywalls_locale": "en"
}

/*
es.json
*/
{
  "adapty_paywalls_locale": "es"
}

/*
pt-BR.json
*/
{
  "adapty_paywalls_locale": "pt-br"
}

// 2. Yerel ayar kodunu çıkarın ve kullanın
using UnityEngine;
using UnityEngine.Localization;
using UnityEngine.Localization.Settings;
using AdaptySDK;

public class PaywallManager : MonoBehaviour
{
    public async void FetchPaywall()
    {
        // Unity'nin Localization sisteminden mevcut yerel ayarı alın
        var locale = LocalizationSettings.SelectedLocale;
        var localeCode = GetAdaptyLocaleCode(locale);
        
        // Yerel ayar kodunu Adapty.GetPaywall veya Adapty.GetPaywallForDefaultAudience metoduna iletin
        Adapty.GetPaywall("placement_id", localeCode, (paywall, error) => {
            if (error != null) {
                // hatayı işle
                return;
            }
            // Paywall'ı kullan
        });
    }
    
    private string GetAdaptyLocaleCode(Locale locale)
    {
        // Unity yerel ayarını Adapty formatına dönüştür
        var localeIdentifier = locale.Identifier.Code;
        return localeIdentifier.ToLower().Replace('_', '-');
    }
}

Bu sayede, uygulamanızın her kullanıcısı için hangi yerelleştirmenin getirileceği üzerinde tam kontrole sahip olursunuz.

Yerelleştirmeleri uygulama: alternatif yöntem

Her yerelleştirme için açıkça bir dil kodu tanımlamak zorunda kalmadan benzer (ama aynı değil) sonuçlar elde edebilirsiniz. Bu yaklaşımda, dil kodunu platformunuzun sunduğu başka nesnelerden çıkarabilirsiniz; örneğin:

using UnityEngine;
using System.Globalization;
using AdaptySDK;

public class PaywallManager : MonoBehaviour
{
    public void FetchPaywall()
    {
        var localeCode = GetSystemLocaleCode();
        
        // Locale kodunu Adapty.GetPaywall veya Adapty.GetPaywallForDefaultAudience metoduna geçirin
        Adapty.GetPaywall("placement_id", localeCode, (paywall, error) => {
            if (error != null) {
                // handle the error
                return;
            }
            // Use the paywall
        });
    }
    
    private string GetSystemLocaleCode()
    {
        // Sistemin mevcut kültür bilgisini al
        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;
    }
}

Bu yaklaşımı birkaç nedenden dolayı önermediğimizi belirtmek gerekir:

iOS’ta tercih edilen diller ile mevcut yerel ayar (locale) aynı şey değildir. Yerelleştirmenin doğru seçilmesini istiyorsanız, ya yerelleştirilmiş string dosyalarıyla önerilen yaklaşımı kullandığınızda kutudan çıktığı gibi çalışan Apple’ın mantığına güvenmeniz ya da bunu kendiniz yeniden oluşturmanız gerekir.
Adapty’nin sunucusunun tam olarak ne alacağını tahmin etmek güçtür. Örneğin iOS’ta, bir cihazda ar_OM@numbers='latn' gibi bir yerel ayar elde edip sunucumuza gönderebilirsiniz. Bu durumda aradığınız ar-om yerelleştirmesini değil, büyük ihtimalle beklemediğiniz ar yerelleştirmesini alırsınız. Bu yaklaşımı kullanmaya karar verseniz bile — tüm ilgili kullanım durumlarını kapsadığınızdan emin olun.