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

Bu neden önemli

Locale kodları, Adapty’nin bir flow veya onboarding için lokalizasyon 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 yüzden Adapty, desteklediği tüm platformlarda tek bir dahili standart kullanır. Bu standardı anlamak, bir kullanıcının hangi lokalizasyonu 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 ayar kodu eşleştirme

SDK v4’te, flow’lar ve onboarding’ler yerel ayar kodlarını farklı şekilde eşleştirir: flow’lar SDK tarafından cihazda, 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 bir flow olarak teslim edilir; 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 lokalizasyon 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 dil alt etiketine geri dönmez. pt-br lokalizasyonuna sahip bir flow için yalnızca pt-br eşleşir: pt-BR, pt_BR ve pt-PT hepsi eşleşmez.

Kod hiçbir yerelleştirmeyle eşleşmediğinde, flow sessizce varsayılan yerel ayarında render edilir — SDK hata döndürmez ve uyarı kaydetmez.

Kod eşleştiğinde, Adapty eşleşen yerelleştirmeyi varsayılan olanla birleştirir: eşleşen yerelleştirmede tanımlanmayan metin ve görseller 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 dili de olan bir flow, en yerelleştirmesi varsa yine en olarak görüntülenir; yalnızca en yerelleştirmesi yoksa de’ye geri döner.

Onboardings

Onboardinglar sunucu tarafında yerelleştirilir ve sunucu kuralları diğer biçimlere de tolerans gösterir. getOnboarding fonksiyonuna bir locale değeri ilettiğinizde:

1. Locale dizesi küçük harfe dönüştürülür ve tüm alt çizgiler (_) kısa çizgilerle (-) değiştirilir
2. Adapty, tam olarak eşleşen locale koduyla yerelleştirmeyi 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 yerelleştirmeyi arar
4. 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.

Lokalizasyonları uygulama

SDK v4’te, bir flow çekerken locale kodu geçmezsiniz — getFlow flow’u tüm lokalizasyonlarıyla birlikte döndürür.

• Builder ile oluşturulan flow’lar: SDK cihaz dilini okumaz; bu nedenle dili uygulamanızda belirleyip AdaptyUI.getFlowConfiguration(forFlow:locale:) fonksiyonuna geçirin. Parametre isteğe bağlıdır — belirtmezseniz flow en dilinde render edilir ya da flow’da en yerelleştirmesi yoksa varsayılan locale kullanılır.
• Özel (remote config) paywall’lar: getFlow, yapılandırılmış tüm yerelleştirmeleri flow.remoteConfigs içinde döndürür. Her giriş bir locale kodu ile config içeriğini (jsonString veya ayrıştırılmış dictionary) içerir. Kendi geri dönüş mekanizmanızla kullanıcıya uyan girişi seçin:

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
}

Adapty, bu locale kodlarını Adapty’deki Locale kodu standardı bölümünde açıklanan biçimde depolar. SDK, remote config’leri bir locale ile eşleştirmez; dolayısıyla hangi kaydın uygulanacağına uygulamanız karar verir.

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’ı almaya çalışırken.

Locale 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, 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 yerel ayar kodu standardı

Yerel ayar kodları için Adapty, biraz değiştirilmiş bir BCP 47 standardı kullanır: her kod, kısa çizgiyle 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).

Locale kod eşleştirme

Adapty, istemci tarafı SDK’dan locale koduyla birlikte bir çağrı aldığında ve bir paywall’ın karşılık gelen yerelleştirmesini aramaya başladığında şunlar olur:

1. Gelen locale dizesi küçük harfe dönüştürülür ve tüm alt çizgiler (_) kısa çizgilerle (-) değiştirilir
2. Ardından tam olarak eşleşen locale koduyla yerelleştirmeyi ararız
3. Eşleşme bulunamazsa, ilk kısa çizgiden önceki alt dizeyi alırız (pt-br için pt) ve eşleşen yerelleştirmeyi ararız
4. Yine eşleşme bulunamazsa, paywall’ın varsayılan locale’i için içeriği döndürürüz

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 yöntem

Yerelleştirmeler konusunu araştırıyorsanız, büyük ihtimalle projenizde yerelleştirilmiş string dosyalarıyla zaten çalışıyorsunuzdur. Bu durumda, her yerelleştirme için ilgili dosyalarınızdan birine 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 aşağıdaki gibi çıkarabilirsiniz:

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

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

Yerelleştirmeleri uygulama: alternatif yöntem

Her yerelleştirme için yerel ayar kodlarını açıkça tanımlamadan da benzer (ancak özdeş olmayan) sonuçlar elde edebilirsiniz. Bu yöntemde, platformunuzun sağladığı başka nesnelerden yerel ayar kodu çıkarırsınız:

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

Bu yaklaşımı birkaç nedenden dolayı önermiyoruz:

1. iOS’ta tercih edilen diller ile mevcut yerel ayar aynı şey değildir. Yerelleştirmenin doğru seçilmesini istiyorsanız ya Apple’ın mantığına güvenmeniz gerekir (bu, yerelleştirilmiş string dosyalarıyla önerilen yaklaşımı kullandığınızda zaten otomatik olarak çalışır) ya da bu mantığı kendiniz yeniden oluşturmanız gerekir.
2. Adapty sunucusunun tam olarak ne alacağını öngörmek güçtür. Örneğin iOS’ta bir cihazdan ar_OM@numbers='latn' gibi bir yerel ayar elde edip sunucumuza göndermek mümkündür. Bu durumda aradığınız ar-om yerelleştirmesini değil, büyük ihtimalle beklenmedik olan ar yerelleştirmesini alırsınız.

Bu yaklaşımı yine de kullanmaya karar verirseniz, ilgili tüm kullanım senaryolarını kapsadığınızdan emin olun.