Android SDK'da yerelleştirmeleri ve yerel ayar kodlarını kullanma

Bu neden önemli

Locale kodları, Adapty bir flow 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 dahili 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 hafifçe değiştirilmiş bir BCP 47 standardı 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 kod eşleştirme

Adapty, bir kullanıcının yerel ayarına uygun lokalizasyonu ararken şu adımlar izlenir:

1. Yerel ayar dizesi küçük harfe dönüştürülür ve tüm alt çizgiler (_) kısa çizgi (-) ile değiştirilir
2. Adapty, yerel kod tam olarak eşleşen lokalizasyonu arar
3. Eşleşme bulunamazsa, Adapty ilk kısa çizgiden önceki alt dizeyi alır (pt-br için pt) ve eşleşen lokalizasyonu arar
4. Yine eşleşme bulunamazsa, Adapty flow’un varsayılan yerel ayarına ait içeriği döndürür

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

Yerelleştirmeleri uygulama

SDK v4’te bir flow çekerken locale kodu geçmenize gerek yok; getFlow fonksiyonu flow’u tüm yerelleştirmeleriyle birlikte döndürür.

• Builder’da oluşturulan flow’lar: SDK cihazın dilini okumaz; bu yüzden dili uygulamanızda belirleyip AdaptyUI.getFlowConfiguration metodunun locale argümanı olarak geçirin. Argüman isteğe bağlıdır — atlarsanız flow en dilinde görüntülenir ya da flow’un en yerelleştirmesi yoksa varsayılan dilde gösterilir. Flow’da bulunmayan bir yerelleştirme talep ederseniz, görünüm hata vermeden varsayılan dile döner; seçilen yerelleştirmede eksik olan metinler de varsayılan dilden alınır.

Rendering in en by default requires Android SDK 4.0.1. In 4.0.0, omitting locale renders the flow’s default localization.

• Özel (remote config) paywall’lar: getFlow, flow.remoteConfigs içindeki tüm yapılandırılmış yerelleştirmeleri döndürür. Her girişin bir locale kodu ve config içeriği (jsonString veya ayrıştırılmış dataMap) bulunur. Kullanıcıya uyan girişi kendi yedek mantığınızla seçin:

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

Yukarıdaki yerel ayar kodu eşleştirme kuralları, Adapty’nin her remote config’de saklanan locale kodlarını nasıl normalleştirdiğini açıklar.

Bu neden önemli

Yerel ayar kodlarının devreye girdiği birkaç senaryo vardır — örneğin, uygulamanızın mevcut yerelleştirmesi için doğru paywall’ı getirmeye çalıştığınızda.

Yerel ayar kodları karmaşık olabilir ve platformdan platforma farklılık gösterebilir; bu nedenle desteklediğimiz tüm platformlar için dahili bir standarda güveniyoruz. Ancak bu kodlar karmaşık olduğundan, sunucumuza doğru yerelleştirmeyi almak için 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 yerel ayar kodu standardı

Adapty, yerel ayar kodları için hafifçe değiştirilmiş bir BCP 47 standardı kullanır: her kod, kısa çizgiyle ayrılmış küçük harf alt etiketlerden oluşur. Birkaç örnek: 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 ve paywall’ın karşılık gelen yerelleştirmesini aramaya başladığında şunlar gerçekleşir:

1. Gelen yerel ayar dizesi küçük harfe dönüştürülür ve tüm alt çizgiler (_) kısa çizgiyle (-) değiştirilir
2. Ardından tam olarak eşleşen yerel ayar koduyla yerelleştirme aranır
3. 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
4. Yine eşleşme bulunamazsa, paywall’ın 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 yerelleştirilmiş dize dosyalarıyla zaten çalışıyorsunuzdur. Bu durumda, her yerelleştirme için ilgili dosyalarınıza hedeflenen Adapty yerel ayar kodunu içeren bir anahtar-değer çifti eklemenizi öneririz. Ardından SDK’mızı çağırırken bu anahtarın değerini şu şekilde kullanın:

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

Bu yöntemle, uygulamanızın her kullanıcısı için hangi yerelleştirmenin getirileceği üzerinde tam kontrol sahibi olursunuz.

Yerelleştirmeleri uygulama: alternatif yol

Her yerelleştirme için açıkça yerel ayar kodları tanımlamadan benzer (ancak özdeş olmayan) sonuçlar elde edebilirsiniz. Bu, platforma ait başka nesnelerden yerel ayar kodu çıkarmak anlamına gelir:

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

Bu yaklaşımı önermiyoruz, çünkü Adapty’nin sunucusuna tam olarak neyin gönderileceğini öngörmek güçtür.

Yine de bu yaklaşımı kullanmaya karar verirseniz — ilgili tüm kullanım senaryolarını kapsadığınızdan emin olun.