İletileri Yerelleştirme

Bu belgede, Android ve iOS'te kullanıcının dil ayarlarına otomatik olarak uyum sağlayan bildirimler göndermek için FCM yerelleştirme alanlarının (*_loc_key ve *_loc_args) kullanımı açıklanmaktadır. Bu sayede sunucunuz, dilden bağımsız tek bir yük göndererek çeviriyi istemci cihaza devredebilir.

FCM Yerelleştirmeye Genel Bakış

Uygulamanızı yerelleştirmek için kullanıcının uygulamasındaki bir dize kaynağı girişine karşılık gelen bir anahtar gönderebilirsiniz. Dinamik bağımsız değişkenlerin aranması ve eklenmesi, cihazın işletim sistemi (OS) tarafından gerçekleştirilir.

1. adım: Uygulamalarınızda yerelleştirilmiş dize kaynakları tanımlayın

FCM yerelleştirmesine başlamak için Android ve iOS projelerinizde gerekli çevirilerin bulunduğundan emin olmanız önemlidir.

Android Kurulumu

Dize kaynaklarını tanımlama: Varsayılan dil dizelerinizi res/values/strings.xml dosyasına girin. *_loc_args parametresine iletmeyi planladığınız tüm dinamik değerler için biçim belirteçleri (%1$s, %2$d vb.) kullanın.

Varsayılan (res/values/strings.xml):

<resources>
    <string name="welcome_title">Welcome, %1$s!</string>
    <string name="new_message_body">You have %1$d new message(s) from %2$s.</string>
</resources>

Çeviri ekleme: ISO dil kodlarını (ör. Fransızca için values-fr, İspanyolca için values-es) kullanarak dile özgü dizinler oluşturun ve anahtarları çevirin.

Fransızca (res/values-fr/strings.xml):

<resources>
    <string name="welcome_title">Bienvenue, %1$s!</string>
    <string name="new_message_body">Vous avez %1$d nouveau(x) message(s) de %2$s.</string>
</resources>

Daha fazla bilgi için aşağıdaki dokümanları kullanın:

• Dize kaynakları - Android Geliştiricileri

• Uygulamanızı yerelleştirme - Android Geliştiricileri

iOS Kurulumu

Dize kaynaklarını tanımlama: Temel dizelerinizi Localizable.strings dosyasında (genellikle Base.lproj klasöründe veya bir dize kataloğunda) tanımlayın. Dinamik değerler için biçim belirleyiciler (%@, %ld vb.) kullanın. Anahtarlar genellikle kural gereği büyük harflerle tanımlanır.

Varsayılan (İngilizce Localizable.strings):

"WELCOME_TITLE" = "Welcome, %@!";
"NEW_MESSAGE_BODY" = "You have %ld new message(s) from %@.";

Çeviri ekleme: Dile özgü .lproj klasörleri oluşturun (veya dize kataloğu kullanarak yerelleştirmeler ekleyin) ve anahtarları çevirin.

Fransızca (fr.lproj/Localizable.strings):

"WELCOME_TITLE" = "Bienvenue, %@!";
"NEW_MESSAGE_BODY" = "Vous avez %ld nouveau(x) message(s) de %@.";

Daha fazla bilgi için aşağıdaki dokümanları kullanın:

• Yerelleştirme - Apple Geliştirici Belgeleri

• Dize kaynakları - Apple Geliştirici Belgeleri

2. adım: FCM mesaj yükünü oluşturun

Sunucunuz, FCM HTTP v1 API'yi kullanarak bildirim gönderirken kaynak anahtarlarını (*_loc_key) ve dinamik verileri (*_loc_args) dize dizisi olarak kullanan tek bir yük oluşturur.

Örnek FCM HTTP v1 Yükü

Yerelleştirme anahtarları, platforma özgü geçersiz kılma bloklarına (android.notification ve apns.payload.aps.alert) yerleştirilir.

{
  "message": {
    "token": "DEVICE_REGISTRATION_TOKEN",

    "android": {
      "notification": {
        // Android keys match strings.xml resource names
        "title_loc_key": "welcome_title",
        "title_loc_args": ["Alice"],
        "body_loc_key": "new_message_body",
        "body_loc_args": ["3", "Bob"]
      }
    },

    "apns": {
      "payload": {
        "aps": {
          "alert": {
            // iOS uses 'title-loc-key' and 'loc-key' (for the body)
            "title-loc-key": "WELCOME_TITLE",
            "title-loc-args": ["Alice"],
            "loc-key": "NEW_MESSAGE_BODY",
            "loc-args": ["3", "Bob"]
          }
        }
      }
    }
  }
}

Yük bağımsız değişkenleriyle ilgili önemli noktalar

• Sıra önemlidir: *_loc_args içindeki dizeler, dize kaynak dosyasındaki yer tutucuların (ör. %1$s, %2$s) gerektirdiği tam sırada olmalıdır.

• Yalnızca dize: *_loc_args dizisindeki tüm öğeler, sayıları temsil etseler bile (örnekteki "3" gibi) dize olmalıdır. İstemci işletim sisteminin dize biçimlendiricisi, biçim belirleyiciye (%ld veya %1$d) göre nihai tür dönüştürme işlemini gerçekleştirir.

3. adım: İstemci işleme ve görüntüleme

Cihaz bildirimi aldığında aşağıdaki adımlar otomatik olarak gerçekleşir:

1. Dil kontrolü: Cihaz, kullanıcının birincil yerel ayarını (ör. Almanca, İtalyanca) tanımlar.

2. Anahtar arama: İşletim sistemi, cihazın yerel ayarı için uygulamanın kaynak dosyalarında karşılık gelen çevrilmiş dizeyi aramak üzere *_loc_key değerini (welcome_title) kullanır.

3. Bağımsız değişken ekleme: OS, *_loc_args (["Alice"]) dizesinden diziyi alır ve değerleri, yerel ayarın biçimlendirme kurallarına (noktalama işaretleri, kelime sırası vb.) uyarak yerelleştirilmiş dizeye ekler.

Bu işlem, her kullanıcının dil tercihlerine göre uyarlanmış ve doğru dil yapısını kullanan bir mesaj almasını sağlarken sunucunuzdan standartlaştırılmış bir yükü korur.

Örnek: Yerelleştirme seçenekleri içeren bildirim mesajı

Aşağıdaki örnek gönderme isteği, Tech konusuna bir bildirim gönderir. Bu bildirim, istemcinin yerelleştirilmiş mesajları görüntülemesi için yerelleştirme seçeneklerini içerir. Kullanıcının cihazındaki görsel efekt örneğini aşağıda görebilirsiniz:

var topicName = 'industry-tech';

var message = {
  android: {
    ttl: 3600000,
    notification: {
      bodyLocKey: 'STOCK_NOTIFICATION_BODY',
      bodyLocArgs: ['FooCorp', '11.80', '835.67', '1.43']
    }
  },
  apns: {
    payload: {
      aps: {
        alert: {
          locKey: 'STOCK_NOTIFICATION_BODY',
          locArgs: ['FooCorp', '11.80', '835.67', '1.43']
        }
      }
    }
  },
  topic: topicName,
};

getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message": {
    "topic":"Tech",
    "android": {
      "ttl":"3600s",
      "notification": {
        "body_loc_key": "STOCK_NOTIFICATION_BODY",
        "body_loc_args": ["FooCorp", "11.80", "835.67", "1.43"]
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "alert": {
            "loc-key": "STOCK_NOTIFICATION_BODY",
            "loc-args": ["FooCorp", "11.80", "835.67", "1.43"]
          }
        }
      }
    }
  }
}'

Daha fazla bilgi edinmek için HTTP v1 referans belgelerindeki AndroidNotification ve ApnsConfig bölümlerini inceleyerek e-posta mesajı gövdesindeki platforma özel bloklarda bulunan anahtarlar hakkında ayrıntılı bilgi edinin. APNS tarafından desteklenen anahtarlar için Apple'ın Yük Anahtarı Referansı'na bakın.