Bản địa hoá thông báo

Tài liệu này trình bày cách sử dụng các trường bản địa hoá FCM (*_loc_key và *_loc_args) để gửi thông báo tự động điều chỉnh theo chế độ cài đặt ngôn ngữ của người dùng trên Android và iOS. Điều này cho phép máy chủ của bạn gửi một tải trọng duy nhất, không phụ thuộc vào ngôn ngữ, uỷ quyền việc dịch cho thiết bị của ứng dụng khách.

FCM Tổng quan về bản địa hoá

Để bản địa hoá ứng dụng, bạn có thể gửi một khoá tương ứng với một mục tài nguyên chuỗi bên trong ứng dụng của người dùng. Hệ điều hành (OS) của thiết bị sẽ xử lý việc tra cứu và chèn các đối số động.

Bước 1: Xác định tài nguyên chuỗi đã bản địa hoá trong ứng dụng

Để bắt đầu bản địa hoá FCM, bạn cần đảm bảo rằng bạn có các bản dịch cần thiết trong dự án Android và iOS.

Thiết lập Android

Xác định tài nguyên chuỗi: Nhập các chuỗi ngôn ngữ mặc định vào res/values/strings.xml. Sử dụng thông số định dạng (%1$s, %2$d, v.v.) cho mọi giá trị động mà bạn dự định truyền vào *_loc_args.

Mặc định (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>

Thêm bản dịch: Tạo thư mục theo ngôn ngữ cụ thể bằng mã ngôn ngữ ISO (ví dụ: values-fr cho tiếng Pháp, values-es cho tiếng Tây Ban Nha) và dịch các khoá.

Tiếng Pháp (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>

Để biết thêm thông tin, hãy tham khảo tài liệu sau:

• Tài nguyên chuỗi – Nhà phát triển Android

• Bản địa hoá ứng dụng – Nhà phát triển Android

Thiết lập iOS

Xác định tài nguyên chuỗi: Xác định các chuỗi cơ sở trong tệp Localizable.strings (thường nằm trong thư mục Base.lproj hoặc Danh mục chuỗi). Sử dụng thông số định dạng (%@, %ld, v.v.) cho các giá trị động. Khoá thường được định nghĩa bằng tất cả chữ in hoa theo quy ước.

Mặc định (tiếng Anh Localizable.strings):

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

Thêm bản dịch: Tạo thư mục .lproj theo ngôn ngữ cụ thể (hoặc thêm bản dịch bằng Danh mục chuỗi) và dịch các khoá.

Tiếng Pháp (fr.lproj/Localizable.strings):

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

Để biết thêm thông tin, hãy tham khảo tài liệu sau:

• Bản địa hoá – Tài liệu dành cho nhà phát triển của Apple

• Tài nguyên chuỗi – Tài liệu dành cho nhà phát triển của Apple

Bước 2: Tạo tải trọng thông báo FCM

Khi gửi thông báo bằng FCM HTTP v1 API, máy chủ của bạn sẽ tạo một tải trọng duy nhất sử dụng các khoá tài nguyên (*_loc_key) và dữ liệu động (*_loc_args) dưới dạng một mảng chuỗi.

Ví dụ về tải trọng HTTP v1 của FCM

Các khoá bản địa hoá được đặt trong các khối ghi đè dành riêng cho nền tảng (android.notification và 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"]
          }
        }
      }
    }
  }
}

Những điểm chính cần xem xét đối với đối số tải trọng

• Thứ tự rất quan trọng: Các chuỗi trong *_loc_args phải theo đúng thứ tự mà phần giữ chỗ yêu cầu trong tệp tài nguyên chuỗi (ví dụ: %1$s, %2$s).

• Chỉ chuỗi: Tất cả phần tử trong mảng *_loc_args phải là chuỗi, ngay cả khi chúng đại diện cho số (như "3" trong ví dụ). Trình định dạng chuỗi của hệ điều hành ứng dụng khách xử lý việc chuyển đổi loại cuối cùng dựa trên thông số định dạng (%ld hoặc %1$d).

Bước 3: Xử lý và hiển thị phía máy khách

Khi thiết bị nhận được thông báo, các bước sau sẽ tự động diễn ra:

1. Kiểm tra ngôn ngữ: Thiết bị xác định ngôn ngữ chính của người dùng (ví dụ: tiếng Đức, tiếng Ý).

2. Tra cứu khoá: Hệ điều hành sử dụng giá trị *_loc_key (welcome_title) để tra cứu chuỗi đã dịch tương ứng trong tệp tài nguyên của ứng dụng cho ngôn ngữ của thiết bị.

3. Chèn đối số: Hệ điều hành lấy mảng từ *_loc_args (["Alice"]) và chèn các giá trị vào chuỗi đã bản địa hoá, tuân thủ các quy tắc định dạng của ngôn ngữ (dấu câu, thứ tự từ, v.v.).

Quy trình này đảm bảo rằng mọi người dùng đều nhận được thông báo phù hợp với ngôn ngữ ưu tiên của họ, sử dụng cấu trúc ngôn ngữ chính xác, đồng thời duy trì tải trọng chuẩn hoá từ máy chủ của bạn.

Ví dụ: thông báo có các lựa chọn bản địa hoá

Yêu cầu gửi trong ví dụ sau đây sẽ gửi thông báo đến chủ đề Tech, bao gồm cả các lựa chọn bản địa hoá để ứng dụng hiển thị thông báo đã bản địa hoá. Dưới đây là ví dụ về hiệu ứng hình ảnh trên thiết bị của người dùng:

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

Để tìm hiểu thêm, hãy xem AndroidNotification và ApnsConfig trong tài liệu tham khảo về HTTP phiên bản 1 để biết thông tin chi tiết đầy đủ về các khoá có sẵn trong các khối dành riêng cho nền tảng trong nội dung thư. Để biết các khoá được APNS hỗ trợ, hãy xem Tài liệu tham khảo về khoá tải trọng của Apple.