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

Bu neden önemli

Locale kodları, Adapty 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 nedenle Adapty, desteklediği her platformda tek bir dahili standarda dayanır. Bu standardı anlamak, bir kullanıcının hangi lokalizasyonu alacağını tahmin etmenize yardımcı olur.

Adapty’de dil kodu standardı

Dil kodları için Adapty, BCP 47 standardının hafifçe değiştirilmiş bir versiyonunu kullanır: her kod, tire ile ayrılmış küçük harf alt etiketlerinden 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 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 iletilir; bu nedenle aşağıdaki kural her ikisini de kapsar.

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 çizgiyle (-) 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 hiçbiri eşleşmez.

Kod hiçbir lokalizasyonla eşleşmediğinde, flow sessizce varsayılan locale ile render edilir — SDK hata döndürmez veya uyarı kaydetmez.

Kod eşleştiğinde ise Adapty, eşleşen lokalizasyonu varsayılan olanla birleştirir: eşleşen lokalizasyonun tanımlamadığı string’ler ve asset’ler varsayılan lokalizasyondan 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 yine en dilinde görüntülenir; yalnızca en yerelleştirmesi yoksa de diline geri döner.

Onboarding’ler

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

1. Locale dizesi küçük harfe dönüştürülür ve tüm alt çizgiler (_) kısa çizgiyle (-) 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’ine ait içeriği döndürür

pt_BR, pt-BR ve pt-br şeklindeki yazımların hepsi aynı onboarding yerelleştirmesine çözümlenir.

Lokalizasyonları uygulama

SDK v4’te, bir flow çekerken locale kodu iletmenize gerek yoktur — getFlow, flow’u tüm lokalizasyonlarıyla birlikte döndürür ve Adapty, flow görünümü oluşturulurken uygun olanı uygular. getFlow ve getFlowForDefaultAudience fonksiyonlarının locale argümanının flow’lar üzerinde hiçbir etkisi yoktur; bu argüman kullanımdan kaldırılmış olup bir uyarı kaydeder.

• Builder’da oluşturulan flow’lar: SDK cihaz dilini okumaz, bu nedenle dili uygulamanızda belirleyip createFlowView veya AdaptyUIFlowPlatformView fonksiyonunun locale argümanı olarak geçirin. Argüman isteğe bağlıdır — atlanırsa flow en dilinde gösterilir ya da flow’un en yerelleştirmesi yoksa varsayılan dil kullanılır.

AdaptyUIFlowView.locale, görünümün hangi yerelleştirmeyle oluşturulduğunu bildirir. Flutter SDK 4.0.3 ile birlikte yerel iOS 4.0.2 ve Android 4.0.1 sürümlerini gerektirir; daha eski yerel SDK’larda null döner.

• Özel (remote config) paywalls: getFlow, flow.remoteConfigs içindeki tüm yapılandırılmış yerelleştirmeleri döndürür. Her giriş bir locale kodu ve yapılandırma içeriği (data dizesi veya ayrıştırılmış dictionary) içerir. Kullanıcıyla eşleşen girişi kendi yedek mekanizmanızla seçin:

final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');
final config = flow.remoteConfigs.firstWhereOrNull((c) => c.locale == 'en') ??
    flow.remoteConfig; // the first remote config, if present
// read your values from config?.dictionary

Adapty, locale kodlarını Adapty’deki Locale kodu standardı bölümünde açıklanan formatta saklar. SDK, remote config’leri bir locale ile eşleştirmez; hangi girişin 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’ı çekmeye çalışırken.

Locale kodları karmaşık olup platformdan platforma farklılık gösterebildiğinden, desteklediğimiz tüm platformlar için dahili bir standart kullanıyoruz. Ancak bu kodlar karmaşık olduğundan, 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 yerel ayar kodu standardı

Adapty, yerel ayar kodları için BCP 47 standardının hafifçe değiştirilmiş bir versiyonunu 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 birlikte bir çağrı aldığında ve ilgili paywall lokalizasyonunu 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 koduna sahip lokalizasyonu arar
3. Eşleşme bulunamazsa, 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, paywall’ın varsayılan yerel ayarı için içeriği döndürü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 yöntem

Yerelleştirmelerle ilgileniyorsanız, büyük ihtimalle projenizde zaten yerelleştirilmiş string dosyalarıyla çalışıyorsunuzdur. Bu durumda, her bir dosyaya ilgili yerelleştirme için hedeflenen Adapty locale kodunu içeren bir anahtar-değer çifti eklemenizi öneririz. Ardından SDK’mızı çağırırken bu anahtara karşılık gelen değeri şu şekilde çıkarabilirsiniz:

// 1. app_en.arb, app_es.arb, app_pt_br.arb dosyalarınızı düzenleyin

/*
app_en.arb
*/
"adapty_paywalls_locale": "en",

/*
app_es.arb
*/
"adapty_paywalls_locale": "es",

/*
app_pt_br.arb
*/
"adapty_paywalls_locale": "pt-br",

// 2. Locale kodunu çıkarın ve kullanın
final locale = AppLocalizations.of(context)!.adapty_paywalls_locale;
// locale kodunu AdaptyUI.getViewConfiguration veya Adapty.getPaywall metoduna iletin

Bu sayede uygulamanızın her kullanıcısı için hangi yerelleştirmenin alınacağını tam olarak kontrol edebilirsiniz.

Yerelleştirmeleri uygulama: alternatif yöntem

Her yerelleştirme için açıkça yerel ayar kodu tanımlamak yerine benzer (ama özdeş olmayan) sonuçlar elde edebilirsiniz. Bu yaklaşımda, platformun sağladığı başka nesnelerden yerel ayar kodunu çıkarırsınız:

final locale = Localizations.localeOf(context).languageCode;
// pass locale code to AdaptyUI.getViewConfiguration or Adapty.getPaywall method

Bu yaklaşımı önermiyoruz; bunun birkaç nedeni var:

1. iOS’ta tercih edilen diller ile mevcut yerel ayar özdeş değildir. Yerelleştirmenin doğru şekilde seçilmesini istiyorsanız, ya Apple’ın mantığına güvenmeniz gerekir (bu, yerelleştirilmiş string dosyalarıyla önerilen yaklaşımı kullandığınızda kutudan çıkar gibi çalışır) ya da bunu kendiniz yeniden oluşturmanız gerekir.
2. Adapty’nin sunucusunun tam olarak ne alacağını öngörmek zordur. Örneğin iOS’ta, bir cihazdan ar_OM@numbers='latn' gibi bir yerel ayar elde edip sunucumuza göndermeniz mümkündür. Bu çağrı için aradığınız ar-om yerelleştirmesini değil, büyük olasılıkla beklemediğiniz ar yerelleştirmesini alırsınız. Yine de bu yaklaşımı kullanmaya karar verirseniz, tüm ilgili kullanım senaryolarını kapsadığınızdan emin olun.