Melokalkan Pesan

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

FCM Ringkasan Pelokalan

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

Langkah 1: Tentukan 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>

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

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, lihat dokumentasi berikut:

• Resource string - Android Developers

• Melokalkan aplikasi Anda - Developer Android

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 ditentukan dalam huruf kapital semua untuk konvensi.

Default (Inggris Localizable.strings):

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

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

Prancis (fr.lproj/Localizable.strings):

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

Untuk mengetahui informasi selengkapnya, lihat dokumentasi berikut:

• Pelokalan - Dokumentasi Developer Apple

• Resource string - Dokumentasi Apple Developer

Langkah 2: Buat payload pesan FCM

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

Contoh Payload HTTP v1 FCM

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 penting: String dalam *_loc_args harus dalam urutan yang sama persis dengan yang diperlukan oleh placeholder dalam file resource string (misalnya, %1$s, %2$s).

• Khusus string: Semua elemen dalam array *_loc_args harus berupa string, meskipun mewakili angka (seperti "3" dalam contoh). String OS klien formatter 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.).

Proses ini memastikan bahwa setiap pengguna menerima pesan yang disesuaikan dengan preferensi bahasa mereka, menggunakan struktur linguistik yang benar, sekaligus mempertahankan payload standar dari server Anda.

Contoh: pesan notifikasi dengan opsi pelokalan

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

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

Untuk 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 kunci yang didukung oleh APNS, lihat Referensi Kunci Payload Apple.