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 khách hàng.

FCM Tổng quan về việc 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 được 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 mình có bản dịch cần thiết trong các 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 của bạn vào res/values/strings.xml. Sử dụng bộ chỉ định đị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 các thư mục dành riêng cho ngôn ngữ bằng cách sử dụ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 bộ chỉ định định dạng (%@, %ld, v.v.) cho các giá trị động. Theo quy ước, các khoá thường được xác định bằng tất cả chữ hoa.

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 các thư mục .lproj theo ngôn ngữ cụ thể (hoặc thêm nội dung bản địa hoá 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 của Apple Developer

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 FCM HTTP phiên bản 1

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 cân nhắc đối với các đối số tải trọng

• Thứ tự quan trọng: Các chuỗi trong *_loc_args phải theo đúng thứ tự mà các 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ả các phần tử trong mảng *_loc_args phải là chuỗi, ngay cả khi chúng đại diện cho các số (như "3" trong ví dụ). Trình định dạng chuỗi của hệ điều hành máy khách sẽ xử lý quá trình chuyển đổi loại cuối cùng dựa trên bộ chỉ định đị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 đây 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 theo 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 lựa chọn ưu tiên về ngôn ngữ 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 được 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á

Ví dụ sau đây gửi yêu cầu gửi thông báo đến chủ đề Tech, bao gồm các lựa chọn bản địa hoá để ứng dụng hiển thị thông báo đã được bản địa hoá. Sau đâ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 HTTP phiên bản 1 để biết đầy đủ thông tin chi tiết về các khoá có trong các khối dành riêng cho nền tảng trong nội dung thông báo. Để biết các khoá mà APNS hỗ trợ, hãy xem Thông tin tham khảo về khoá tải trọng của Apple.