React Native SDK'da yerelleştirmeleri ve locale kodlarını kullanma

Bu neden önemli

Locale kodları, Adapty’nin bir flow veya onboarding için lokalizasyonu 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 tüm platformlarda tek bir dahili standarda dayanır. Bu standardı anlamak, kullanıcının hangi lokalizasyonu alacağını öngörmenize yardımcı olur.

Adapty’de locale kodu standardı

Locale kodları için Adapty, hafifçe değiştirilmiş bir BCP 47 standardı kullanır: her kod, tirelerle 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 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 sunulur; dolayısıyla aşağıdaki kural her ikisi için de geçerlidir.

Eşleşme birebir gerçekleşir. 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 (_) tire (-) ile değiştirmez ve yalnızca dil etiketiyle eşleşmeye çalışmaz. 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 yerelleştirmeyle eşleşmediğinde, flow sessizce varsayılan dilde görüntülenir — SDK hata döndürmez ve uyarı kaydetmez.

Kod eşleştiğinde ise 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.

Locale kodunu atlamak, flow’un varsayılan yerelleştirmesini istemekle aynı şey değildir: SDK sabit olarak en kullanır. Varsayılan locale’i de olan bir flow, en yerelleştirmesi varsa en olarak görüntülenir; yalnızca en yerelleştirmesi yoksa de’ye geri döner.

Warning

Yerel ayar kodunu kontrol panelinde yapılandırıldığı şekliyle iletin — küçük harfli alt etiketler tire ile ayrılmış olmalıdır. Cihaz yerel ayar tanımlayıcısını olduğu gibi geçirmeyin: react-native-localize içindeki getLocales()[0].languageTag pt-BR döndürür ve bu varsayılan yerelleştirmeye geri döner. Değeri iletmeden önce uygulamanızda dönüştürün.

Onboarding’ler

Onboarding’ler sunucu tarafında yerelleştirilir ve sunucu kuralları diğer biçimleri de kabul eder. getOnboarding fonksiyonuna bir locale değeri ilettiğinizde:

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

SDK v4’te, bir flow çekerken yerel ayar kodu geçirmezsiniz — getFlow, tüm yerelleştirmeleriyle birlikte flow’u döndürür ve Adapty, flow görünümü oluşturulurken uygun olanı uygular.

Builder’da oluşturulan flow’lar: SDK cihazın yerel ayarını okumaz; bu nedenle uygulamanızda çözümleyip createFlowView fonksiyonunun locale parametresi olarak ya da gömülü AdaptyFlowView bileşeninin params prop’u aracılığıyla geçirin. Bu parametre isteğe bağlıdır — belirtmezseniz flow en dilinde görüntülenir; flow’un en yerelleştirmesi yoksa varsayılan yerel ayarında görüntülenir.
```
import { createFlowView } from 'react-native-adapty';

const view = await createFlowView(flow, { locale: 'es' });
```

view.locale, görünümün gerçekte hangi yerelleştirmeyle oluşturulduğunu bildirir — istediğiniz locale mevcutsa onu, yoksa flow’un varsayılanını döndürür. locale parametresi ve view.locale her ikisi de React Native SDK 4.0.2 veya sonrasını gerektirir; daha eski sürümlerde view.locale undefined döner.

Yerleşik AdaptyFlowView bileşeni kendi görünümünü oluşturduğundan, kodunuzun locale okuyacağı bir nesne yoktur. Yerelleştirmeyi bunun yerine onAppeared handler’ının aldığı nesneden alın:

  <AdaptyFlowView
    flow={flow}
    params={{ locale: 'es' }}
    onAppeared={(view) => setScreenLocale(view.locale)}
  />

onAppeared argümanı React Native SDK 4.0.3 veya sonraki bir sürümü gerektirir.

Özel (remote config) paywall’lar: getFlow, yapılandırılmış her lokalizasyonu flow.remoteConfigs içinde döndürür. Her girişin bir lang kodu ve bir data nesnesi vardır. Kullanıcıya uyan girişi kendi yedek mantığınızla seçin:


const flow = await adapty.getFlow('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 biçimde 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

Locale 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ışırken.

Locale kodları karmaşık olduğundan ve platformdan platforma değişebildiğinden, desteklediğimiz tüm platformlar için dahili bir standart kullanırız. Ancak bu kodlar karmaşık olduğu için, doğru yerelleştirmeyi almak üzere sunucumuza tam olarak ne gönderdiğinizi ve sonrasında ne olduğunu anlamanız gerçekten önemlidir — böylece her zaman beklediğinizi alırsınız.

Adapty’de locale kodu standardı

Yerel ayar kodu eşleştirme

Adapty, istemci tarafı SDK’dan yerel ayar koduyla bir çağrı aldığında ve bir paywall’a ait ilgili yerelleştirmeyi aramaya başladığında şunlar olur:

Gelen yerel ayar dizesi küçük harfe dönüştürülür ve tüm alt çizgiler (_) kısa çizgiyle (-) değiştirilir
Ardından 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 eşleşen yerelleştirme aranır
Yine eşleşme bulunamazsa, paywall’ın varsayılan yerel ayarı için içerik döndürülür

Bu şekilde '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 hakkında düşünüyorsanız, muhtemelen projenizde yerelleştirilmiş dize dosyalarıyla zaten uğraşıyorsunuzdur. Durum buysa, ilgili yerelleştirmeler için dosyalarınızın her birine, amaçlanan Adapty locale kodunu içeren bir anahtar-değer yerleştirmenizi öneririz. Ardından SDK’mızı çağırırken bu anahtarın değerini şu şekilde çıkarı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 şekilde, uygulamanızın her kullanıcısı için hangi yerelleştirmenin getirileceği konusunda tam kontrole sahip olduğunuzdan emin olabilirsiniz.

Yerelleştirmeleri uygulama: diğer yöntem

Her yerelleştirme için locale kodlarını açıkça tanımlamadan benzer (ama aynı olmayan) sonuçlar elde edebilirsiniz. Bu, cihazdan bir locale kodu çıkarmak anlamına gelir; örneğin react-native-localize aracılığıyla:


const fetchPaywall = async () => {
  // getLocales() returns the user's preferred locales in BCP-47 format (e.g., 'en-US', 'pt-BR')
  const locale = RNLocalize.getLocales()[0].languageTag;
  // pass locale code to adapty.getPaywall or adapty.getPaywallForDefaultAudience method
  const paywall = await adapty.getPaywallForDefaultAudience('placement_id', locale);
};

Bu yaklaşımı birkaç nedenden dolayı önermediğimizi unutmayın:

iOS’ta tercih edilen diller ve mevcut bölgesel locale aynı değildir. Yerelleştirmenin doğru seçilmesini istiyorsanız, ya Apple’ın çözümleme mantığına güvenmeniz gerekir — ki bu, yerelleştirilmiş dize dosyalarıyla önerilen yaklaşımı kullandığınızda hazır olarak çalışır — ya da onu kendiniz yeniden oluşturmanız gerekir.
Cihaz locale’i, Adapty’de yapılandırdığınız hiçbir yerelleştirmeyle eşleşmeyebilir. Bu durumda SDK, ilk alt etiket eşleşmesine veya nihayetinde en’e geri döner — ki bu, o kullanıcı için varsayılan yapmak isteyeceğiniz dil olmayabilir.

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