Capacitor SDK'da yerelleştirme 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 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 kullanılan yerel ayar kodu standardı

Adapty, yerel ayar kodları için hafifçe değiştirilmiş bir BCP 47 standardı kullanır: her kod, küçük harfli alt etiketlerden oluşur ve bunlar kısa çizgilerle ayrılır. Birkaç örnek: 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ı şekillerde eşleştirir: flow’lar SDK tarafından cihazda yerelleştirilirken, onboarding’ler 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; bu nedenle aşağıdaki kural her ikisini de kapsar.

Eşleşme tam olarak gerçekleşir. 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 çizgiyle (-) değiştirmez ve 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 lokalizasyonla eşleşmediğinde, flow sessizce varsayılan lokalizasyonda görüntülenir — SDK hata döndürmez ve uyarı kaydetmez.

Kod eşleştiğinde ise Adapty, eşleşen lokalizasyonu varsayılan lokalizasyonla birleştirir: eşleşen lokalizasyonda tanımlanmamış 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 en dilinde görüntülenir; yalnızca en yerelleştirmesi yoksa de diline geri döner.

Onboarding’ler

Onboarding’ler sunucuda yerelleştirilir ve sunucu kuralları diğer biçimleri de 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 çizgi (-) ile 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 (pt-br için pt) alır 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.

Yerelleştirmelerin Uygulanması

SDK v4’te, bir flow getirirken locale kodu geçirmezsiniz — getFlow, flow’u tüm yerelleştirmeleriyle birlikte döndürür ve Adapty, flow görünümü oluşturulurken bunlardan birini uygular.

• Builder’da oluşturulan flow’lar: SDK, cihaz locale’ini okumaz; bu nedenle bunu uygulamanızda çözümleyin ve createFlowView’ın locale seçeneği olarak geçirin. Bu isteğe bağlıdır — atarsanız flow en dilinde ya da flow’un en yerelleştirmesi yoksa varsayılan locale dilinde görüntülenir.

  import { createFlowView } from '@adapty/capacitor';
  
  const view = await createFlowView(flow, { locale: 'es' });

view.locale, view’ün oluşturulduğu yerelleştirmeyi bildirir. Hem locale seçeneği hem de view.locale, Capacitor SDK 4.0.1-beta.1 gerektirir ve view.locale, önceki sürümlerde undefined olur. onAppeared işleyicisi aynı değeri bildirir.

• Özel (remote config) paywall’lar: getFlow, flow.remoteConfigs içindeki yapılandırılmış tüm yerelleştirmeleri döndürür. Her girdinin bir lang kodu ve bir data nesnesi vardır. Kendi yedek mantığınızla kullanıcıya uyan girdiyi seçin:

const flow = await adapty.getFlow({ placementId: 'placement_id' });
const config = flow.remoteConfigs?.find((c) => c.lang === 'en') ?? flow.remoteConfigs?.[0];
// read your values from config?.data

Adapty, bu lang kodlarını Adapty’deki Yerel Ayar Kodu Standardı bölümünde açıklanan formatta saklar. SDK, remote config’leri bir yerel ayarla eşleştirmez; dolayısıyla hangi girişin uygulanacağına uygulamanız karar verir.

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’u getirmeye çalıştığınızda.

Yerel ayar kodları karmaşık bir yapıya sahiptir ve platformdan platforma farklılık gösterebilir; bu nedenle desteklediğimiz tüm platformlar için dahili bir standart kullanıyoruz. Ancak bu kodlar karmaşık olduğundan, sunucumuza ne gönderdiğinizi ve ardından ne olduğunu tam olarak 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 ç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 paywall için ilgili bir yerelleştirme aramaya başladığında şunlar olur:

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 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ı için 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, muhtemelen projenizde zaten yerelleştirilmiş string dosyalarıyla çalışıyorsunuzdur. Bu durumda, ilgili yerelleştirmeler için her dosyaya Adapty yerel ayar 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 alın:

// 1. Modify your localization files (e.g., using react-i18next)

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

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

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

// 2. Extract and use the locale code

const MyComponent = () => {
  const { t } = useTranslation();
  
  const fetchPaywall = async () => {
    const locale = t('adapty_paywalls_locale');
    // pass locale code to adapty.getPaywall or adapty.getPaywallForDefaultAudience method
    const paywall = await adapty.getPaywallForDefaultAudience('placement_id', locale);
  };
};

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ımlamadan da benzer (ancak özdeş olmayan) sonuçlar elde edebilirsiniz. Bu yaklaşımda, platformunuzun sağladığı başka nesnelerden yerel ayar kodu çıkarmak gerekir; örneğin:

const getLocaleCode = () => {
  if (Capacitor.getPlatform() === 'ios') {
    return navigator.language || 'en';
  } else {
    return navigator.language || 'en';
  }
};

const fetchPaywall = async () => {
  const locale = getLocaleCode();
  // pass locale code to adapty.getPaywall or adapty.getPaywallForDefaultAudience method
  const paywall = await adapty.getPaywallForDefaultAudience('placement_id', locale);
};

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

1. iOS’ta tercih edilen diller ile mevcut locale aynı değildir. Yerelleştirmenin doğru seçilmesini istiyorsanız, Apple’ın mantığına güvenmeniz gerekir; bu mantık, yerelleştirilmiş string dosyalarıyla önerilen yaklaşımı kullandığınızda kutudan çıktığı gibi çalışır. Alternatif olarak bu mantığı kendiniz de yeniden oluşturabilirsiniz.
2. Adapty sunucusunun tam olarak ne alacağını tahmin etmek güçtür. Örneğin iOS’ta bir cihazda ar_OM@numbers='latn' gibi bir locale elde edip bunu sunucumuza gönderebilirsiniz. Bu durumda aradığınız ar-om yerelleştirmesini değil, büyük ihtimalle beklenmedik olan ar yerelleştirmesini alırsınız. Yine de bu yaklaşımı kullanmaya karar verirseniz, ilgili tüm kullanım senaryolarını kapsadığınızdan emin olun.