Melokalkan Pesan

Dokumentasi ini menguraikan penggunaan kolom pelokalan FCM (*_loc_key dan *_loc_args) untuk mengirimkan notifikasi yang otomatis disesuaikan dengan setelan bahasa pengguna di Android dan iOS. Dengan begitu, server Anda dapat mengirimkan satu payload yang tidak bergantung pada bahasa, sehingga terjemahan akan didelegasikan ke perangkat klien.

Ringkasan Pelokalan FCM

Untuk melokalkan aplikasi, Anda dapat mengirimkan kunci yang sesuai dengan entri resource string di dalam aplikasi pengguna. Sistem operasi (OS) perangkat akan menangani pencarian dan penyisipan argumen dinamis.

Catatan: Lihat AndroidNotification dan ApnsConfig dalam dokumentasi referensi HTTP v1 untuk mengetahui detail lengkap tentang kunci yang tersedia di blok khusus platform dalam isi pesan. Untuk mengetahui kunci yang didukung oleh APNS, lihat Referensi Kunci Payload Apple.

Kolom FCM	Deskripsi	Tindakan Klien
title_loc_key	Kunci untuk string judul di resource string aplikasi klien.	OS menemukan string yang sesuai dalam file aplikasi yang dilokalkan.
body_loc_key	Kunci untuk string isi pesan di resource string aplikasi klien.	OS menemukan string yang sesuai dalam file aplikasi yang dilokalkan.
title_loc_args	Array nilai string dinamis yang akan diganti ke dalam string title_loc_key.	OS menyisipkan argumen ini ke dalam penentu format string yang dilokalkan.
body_loc_args	Array nilai string dinamis yang akan diganti ke dalam string body_loc_key.	OS menyisipkan argumen ini ke dalam penentu format string yang dilokalkan.

Langkah 1: Menentukan resource string yang dilokalkan di aplikasi Anda

Untuk mulai menggunakan pelokalan FCM, Anda harus memastikan bahwa Anda memiliki terjemahan yang diperlukan di project Android dan iOS Anda.

Penyiapan Android

Tentukan resource string: Masukkan string bahasa default Anda di res/values/strings.xml. Gunakan penentu format (%1$s, %2$d, dll.) untuk nilai dinamis yang ingin Anda teruskan di *_loc_args.

Default (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>

Tambahkan terjemahan: Buat direktori khusus bahasa menggunakan kode bahasa ISO (misalnya, values-fr untuk bahasa Prancis, values-es untuk bahasa Spanyol) dan terjemahkan kuncinya.

Bahasa Prancis (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>

Untuk mengetahui informasi selengkapnya, gunakan dokumentasi berikut:

• Resource string - Android Developers

• Melokalkan aplikasi Anda - Android Developers

Penyiapan iOS

Tentukan resource string: Tentukan string dasar Anda dalam file Localizable.strings (biasanya di folder Base.lproj atau Katalog String). Gunakan penentu format (%@, %ld, dll.) untuk nilai dinamis. Kunci sering kali menggunakan huruf besar semua untuk konvensi.

Default (bahasa Inggris Localizable.strings):

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

Tambahkan terjemahan: Buat folder .lproj khusus bahasa (atau tambahkan pelokalan menggunakan Katalog String) dan terjemahkan kuncinya.

Bahasa Prancis (fr.lproj/Localizable.strings):

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

Untuk mengetahui informasi selengkapnya, gunakan dokumentasi berikut:

• Pelokalan - Dokumentasi Apple Developer

• Resource string - Dokumentasi Apple Developer

Langkah 2: Membuat payload pesan FCM

Saat mengirimkan notifikasi menggunakan FCM HTTP v1 API, server Anda akan membuat satu payload yang menggunakan kunci resource (*_loc_key) dan data dinamis (*_loc_args) sebagai array string.

Contoh Payload FCM HTTP v1

Kunci pelokalan ditempatkan dalam blok penggantian khusus platform (android.notification dan apns.payload.aps.alert).

{
  "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"]
          }
        }
      }
    }
  }
}

Pertimbangan utama untuk argumen payload

• Urutan itu penting: Urutan string dalam *_loc_args harus sama persis dengan yang diperlukan di placeholder dalam file resource string (misalnya, %1$s, %2$s).

• Hanya string: Semua elemen dalam array *_loc_args harus berupa string, meskipun mewakili angka (seperti "3" dalam contoh). Pemformat string OS klien akan menangani konversi jenis akhir berdasarkan penentu format (%ld atau %1$d).

Langkah 3: Pemrosesan dan tampilan klien

Saat perangkat menerima notifikasi, langkah-langkah berikut akan terjadi secara otomatis:

1. Pemeriksaan bahasa: Perangkat mengidentifikasi lokalitas utama pengguna (misalnya, Jerman, Italia).

2. Pencarian kunci: OS menggunakan nilai *_loc_key (welcome_title) untuk mencari string terjemahan yang sesuai dalam file resource aplikasi untuk lokalitas perangkat.

3. Penyisipan argumen: OS mengambil array dari *_loc_args (["Alice"]) dan menyisipkan nilai ke dalam string yang dilokalkan, dengan mematuhi aturan pemformatan lokalitas (tanda baca, urutan kata, dll.).

Lokalitas Perangkat	title_loc_key: welcome_title	title_loc_args: ["Alice"]	Tampilan Judul Akhir
Inggris	"Welcome, %1$s!"	Alice	"Welcome, Alice!"
Prancis	"Bienvenue, %1$s!"	Alice	"Bienvenue, Alice!"
Jerman	"Willkommen, %1$s!"	Alice	"Willkommen, Alice!"

Proses ini memastikan bahwa setiap pengguna menerima pesan yang disesuaikan dengan preferensi bahasanya dan memiliki struktur linguistik yang tepat, dengan tetap mempertahankan payload standar dari server Anda.

Contoh: pesan notifikasi dengan opsi pelokalan

Contoh permintaan kirim berikut mengirimkan notifikasi ke topik Tech, yang juga berisi opsi pelokalan agar klien dapat menampilkan pesan yang dilokalkan. Berikut adalah contoh efek visual pada perangkat pengguna:

Node.js

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);
  });

REST

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"]
          }
        }
      }
    }
  }
}'

Guna mempelajari lebih lanjut, lihat AndroidNotification dan ApnsConfig di dokumentasi referensi HTTP v1 untuk mengetahui detail lengkap tentang kunci yang tersedia di blok khusus platform dalam isi pesan. Untuk mengetahui kunci yang didukung oleh APNS, lihat Referensi Kunci Payload Apple.