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

Bu neden önemli

Adapty bir flow için yerelleştirme seçerken ve özel bir paywall için remote config okurken locale kodları 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, kullanıcının hangi yerelleştirmeyi alacağını öngörmenize yardımcı olur.

Adapty’de yerel ayar kodu standardı

Adapty, yerel ayar kodları için hafif değiştirilmiş bir BCP 47 standardı kullanır: her kod, tire ile 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).

Yerel kod eşleştirme

Adapty, kullanıcının yerel ayarıyla eşleşen yerelleştirmeyi ararken şu adımları izler:

Yerel ayar dizesi küçük harfe dönüştürülür ve tüm alt çizgiler (_) kısa çizgilerle (-) değiştirilir
Adapty, tam olarak eşleşen yerel kod için yerelleştirmeyi arar
Eşleşme bulunamazsa, Adapty ilk kısa çizgiden önceki alt dizeyi alır (pt-br için pt) ve eşleşen yerelleştirmeyi arar
Yine eşleşme bulunamazsa, Adapty varsayılan en yerelleştirmesini döndürür

Bu sayede 'pt_BR', pt-BR ve pt-br hepsi aynı yerelleştirmeye karşılık gelir.

Yerelleştirmeleri Uygulamak

SDK v4’te bir flow çekerken locale kodu göndermenize gerek yok.

Flow Builder ve Paywall Builder paywallları: Adapty, yerelleştirmeyi cihazdan ve builder’da yapılandırdığınız yerelleştirmelerden otomatik olarak çözümler. Flow’u createFlowView ile render edin — locale koduna gerek yok.
Özel (remote config) paywalllar: getFlow, yapılandırılmış her yerelleştirmeyi flow.remoteConfigs içinde döndürür. Her giriş, bir locale kodu ve dataMap içeren bir AdaptyRemoteConfig’tir. Kullanıcıyla eşleşen girişi kendi fallback mantığınızla seçin:


Adapty.getFlow("YOUR_PLACEMENT_ID")
    .onSuccess { flow ->
        val config = flow.remoteConfigs.firstOrNull { it.locale == "en" }
            ?: flow.remoteConfigs.firstOrNull()
        // read your values from config?.dataMap
    }
    .onError { error ->
        // handle the error
    }

Yukarıdaki locale kod eşleştirme kuralları, Adapty’nin her remote config üzerinde 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’ı almaya çalışırken.

Yerel ayar kodları karmaşık olduğundan ve platformdan platforma farklılık gösterebildiğinden, desteklediğimiz tüm platformlar için dahili bir standarda dayanıyoruz. Ancak bu kodlar karmaşık olduğu için, doğru yerelleştirmeyi almak üzere sunucumuza tam olarak ne gönderdiğinizi ve ardından ne olduğunu anlamanız son derece önemlidir; böylece her zaman beklediğinizi alırsınız.

Adapty’de locale kodu standardı

Adapty, locale 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. 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 bir çağrı aldığında ve paywall için ilgili yerelleştirmeyi aramaya başladığında ş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.
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 bu kodla eşleşen yerelleştirme aranır.
Yine eşleşme bulunamazsa varsayılan en yerelleştirmesi 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 alacaktır.

Lokalizasyonları uygulama: önerilen yöntem

Lokalizasyonlarla ilgileniyorsanız, büyük ihtimalle projenizdeki lokalize edilmiş string kaynaklarıyla zaten çalışıyorsunuzdur. Eğer öyleyse, her kaynak dosyanıza ilgili lokalizasyon için Adapty locale kodu içeren bir anahtar-değer çifti eklemenizi öneririz. Ardından SDK’mızı çağırırken bu anahtarın değerini şu şekilde çekebilirsiniz:

// 1. Adapty yerel ayar kodunu Compose Multiplatform kaynaklarınıza ekleyin

/*
composeResources/values/strings.xml (varsayılan — İngilizce)
*/
<string name="adapty_paywalls_locale">en</string>

/*
composeResources/values-es/strings.xml (İspanyolca)
*/
<string name="adapty_paywalls_locale">es</string>

/*
composeResources/values-pt-rBR/strings.xml (Portekizce — Brezilya)
*/
<string name="adapty_paywalls_locale">pt-br</string>

// 2. Yerel ayar kodunu çıkarın ve kullanın

suspend fun fetchPaywall() {
    val locale = getString(Res.string.adapty_paywalls_locale)
    Adapty.getPaywall(
        placementId = "YOUR_PLACEMENT_ID",
        locale = locale
    ).onSuccess { paywall ->
        // istenen paywall
    }.onError { error ->
        // hatayı işle
    }
}

Bu sayede uygulamanızın her kullanıcısı için hangi yerelleştirmenin alınacağı üzerinde tam kontrol sahibi olursunuz.

Compose Multiplatform kaynakları kullanmıyorsanız, aynı fikir kullandığınız herhangi bir yerelleştirme kütüphanesi için de geçerlidir (örneğin, moko-resources) — Adapty yerel ayar kodunu her yerel ayarın kaynak paketinde bir dize olarak saklayın ve SDK’yı çağırmadan önce okuyun.

Yerelleştirmeleri uygulama: alternatif yol

Her yerelleştirme için açıkça dil kodu tanımlamadan da benzer (ancak aynı değil) sonuçlar elde edebilirsiniz. Bu yaklaşım, dil kodunu doğrudan cihazdan çıkarmak anlamına gelir; ancak commonMain içinde ortak bir dil kodu API’si olmadığından expect/actual bildirimleri gereklidir:

// commonMain
expect fun currentLocaleTag(): String

// androidMain
actual fun currentLocaleTag(): String = Locale.getDefault().toLanguageTag()

// iosMain
actual fun currentLocaleTag(): String = NSLocale.currentLocale.localeIdentifier

// commonMain — pass the locale code to Adapty

suspend fun fetchPaywall() {
    Adapty.getPaywall(
        placementId = "YOUR_PLACEMENT_ID",
        locale = currentLocaleTag()
    ).onSuccess { paywall ->
        // istenen paywall
    }.onError { error ->
        // hatayı işle
    }
}

Birkaç nedenden dolayı bu yaklaşımı önermiyoruz:

iOS’ta kullanıcının tercih ettiği dil ile cihazın bölgesel yerel ayarı aynı değildir. NSLocale.currentLocale.localeIdentifier, kullanıcının uygulamanızı gerçekte hangi dilde okuduğuyla örtüşmeyebilecek bölgesel yerel ayarı döndürür. Yerelleştirilmiş string dosyaları kullanan iOS uygulamaları, her ikisini birleştirmek için Apple’ın çözümleme mantığına dayanır; bu da yukarıdaki önerilen yaklaşımla doğrudan çalışır.
Cihazın tam olarak ne döndüreceğini ve bunun Adapty’deki bir yerelleştirmeyle eşleşip eşleşmeyeceğini tahmin etmek güçtür. Cihaz yerel ayarı, Adapty’de yapılandırmadığınız uzantılar veya bölge kodları içerebilir; bu durumda SDK, ilk alt etikete göre eşleşmeye ya da nihayetinde en diline geri döner. Bu yaklaşımı kullanmaya karar verirseniz, ilgili tüm kullanım senaryolarını kapsadığınızdan emin olun.