แปลข้อความ

เอกสารนี้อธิบายการใช้FCMฟิลด์การแปล (*_loc_key และ *_loc_args) เพื่อแสดงการแจ้งเตือนที่ปรับเปลี่ยนโดยอัตโนมัติ ตามการตั้งค่าภาษาของผู้ใช้ใน Android และ iOS ซึ่งจะช่วยให้เซิร์ฟเวอร์ส่งเพย์โหลดเดียวที่ไม่ขึ้นกับภาษา โดยมอบหมายการแปลให้กับอุปกรณ์ไคลเอ็นต์

FCM ภาพรวมการแปล

หากต้องการแปลแอปเป็นภาษาท้องถิ่น คุณสามารถส่งคีย์ที่สอดคล้องกับรายการ ทรัพยากรสตริงภายในแอปพลิเคชันของผู้ใช้ ระบบปฏิบัติการ (OS) ของอุปกรณ์จะจัดการ การค้นหาและการแทรกอาร์กิวเมนต์แบบไดนามิก

ขั้นตอนที่ 1: กำหนดแหล่งข้อมูลสตริงที่แปลแล้วในแอป

หากต้องการเริ่มต้นใช้งานFCMการแปลแอปเป็นภาษาต่างๆ คุณต้องตรวจสอบว่ามีคำแปลที่จำเป็นในโปรเจ็กต์ Android และ iOS

การตั้งค่า Android

กำหนดทรัพยากรสตริง: ป้อนสตริงภาษาเริ่มต้นใน res/values/strings.xml ใช้ตัวระบุรูปแบบ (%1$s, %2$d ฯลฯ) สำหรับค่าแบบไดนามิกที่คุณวางแผนจะส่งใน *_loc_args

ค่าเริ่มต้น (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>

เพิ่มคำแปล: สร้างไดเรกทอรีเฉพาะภาษาโดยใช้รหัสภาษา ISO (เช่น values-fr สำหรับภาษาฝรั่งเศส values-es สำหรับภาษาสเปน) แล้วแปลคีย์

ฝรั่งเศส (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>

ดูข้อมูลเพิ่มเติมได้ที่เอกสารประกอบต่อไปนี้

• แหล่งข้อมูลสตริง - นักพัฒนาแอป Android

• แปลแอป - นักพัฒนาแอป Android

การตั้งค่า iOS

กำหนดทรัพยากรสตริง: กำหนดสตริงฐานในไฟล์ Localizable.strings (โดยปกติจะอยู่ในโฟลเดอร์ Base.lproj หรือแคตตาล็อกสตริง) ใช้ตัวระบุรูปแบบ (%@, %ld ฯลฯ) สำหรับค่าแบบไดนามิก โดยทั่วไปแล้ว คีย์จะกำหนดเป็นตัวพิมพ์ใหญ่ทั้งหมดตามธรรมเนียม

ค่าเริ่มต้น (อังกฤษ Localizable.strings):

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

เพิ่มคำแปล: สร้างโฟลเดอร์ .lproj เฉพาะภาษา (หรือเพิ่ม การแปลโดยใช้ String Catalog) และแปลคีย์

ฝรั่งเศส (fr.lproj/Localizable.strings):

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

ดูข้อมูลเพิ่มเติมได้ที่เอกสารประกอบต่อไปนี้

• การแปล - เอกสารประกอบสำหรับนักพัฒนาแอปของ Apple

• ทรัพยากรสตริง - เอกสารประกอบของ Apple Developer

ขั้นตอนที่ 2: สร้างเพย์โหลดข้อความ FCM

เมื่อส่งการแจ้งเตือนโดยใช้ FCM HTTP v1 API เซิร์ฟเวอร์ของคุณจะสร้างเพย์โหลดเดียวที่ใช้คีย์ทรัพยากร (*_loc_key) และข้อมูลแบบไดนามิก (*_loc_args) เป็นอาร์เรย์ของสตริง

ตัวอย่าง FCM เพย์โหลด HTTP v1

คีย์การแปลจะอยู่ในบล็อกการลบล้างเฉพาะแพลตฟอร์ม (android.notification และ 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"]
          }
        }
      }
    }
  }
}

ข้อควรพิจารณาที่สำคัญสำหรับอาร์กิวเมนต์ของเพย์โหลด

• ลำดับมีความสำคัญ: สตริงใน *_loc_args ต้องอยู่ในลำดับที่แน่นอน ตามที่ตัวยึดตำแหน่งในไฟล์ทรัพยากรสตริงกำหนด (เช่น %1$s, %2$s)

• สตริงเท่านั้น: องค์ประกอบทั้งหมดในอาร์เรย์ *_loc_args ต้องเป็นสตริง แม้ว่าจะเป็นตัวเลข (เช่น "3" ในตัวอย่าง) String formatter ของระบบปฏิบัติการไคลเอ็นต์จะจัดการการแปลงประเภทขั้นสุดท้ายตามตัวระบุรูปแบบ (%ld หรือ %1$d)

ขั้นตอนที่ 3: การประมวลผลและการแสดงผลฝั่งไคลเอ็นต์

เมื่ออุปกรณ์ได้รับการแจ้งเตือน ระบบจะทำตามขั้นตอนต่อไปนี้โดยอัตโนมัติ

1. การตรวจสอบภาษา: อุปกรณ์จะระบุภาษาหลักของผู้ใช้ (เช่น เยอรมัน อิตาลี)

2. การค้นหาคีย์: ระบบปฏิบัติการจะใช้*_loc_keyค่า (welcome_title) เพื่อค้นหา สตริงที่แปลที่สอดคล้องกันในไฟล์ทรัพยากรของแอปสำหรับ ภาษาของอุปกรณ์

3. การแทรกอาร์กิวเมนต์: ระบบปฏิบัติการจะนำอาร์เรย์จาก *_loc_args (["Alice"]) และแทรกค่าลงในสตริงที่แปลแล้ว โดยจะใช้กฎการจัดรูปแบบของภาษา (เครื่องหมายวรรคตอน ลำดับคำ ฯลฯ)

กระบวนการนี้จะช่วยให้มั่นใจได้ว่าผู้ใช้ทุกคนจะได้รับข้อความที่ปรับให้เหมาะกับค่ากำหนดภาษาของตน โดยใช้โครงสร้างทางภาษาที่ถูกต้อง ขณะเดียวกันก็ยังคงเพย์โหลดที่ได้มาตรฐานจากเซิร์ฟเวอร์ของคุณ

ตัวอย่าง: ข้อความแจ้งเตือนที่มีตัวเลือกการแปล

ตัวอย่างคำขอส่งต่อไปนี้จะส่งการแจ้งเตือนไปยังหัวข้อ Tech รวมถึงตัวเลือกการแปลสำหรับไคลเอ็นต์เพื่อแสดงข้อความที่แปลแล้ว ตัวอย่างเอฟเฟกต์ภาพบนอุปกรณ์ของผู้ใช้

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

ดูข้อมูลเพิ่มเติมได้ที่ AndroidNotification และ ApnsConfig ในเอกสารข้อมูลอ้างอิง HTTP v1 เพื่อดูรายละเอียดทั้งหมดเกี่ยวกับคีย์ที่มีอยู่ในบล็อกเฉพาะแพลตฟอร์มใน เนื้อหาของข้อความ ดูคีย์ที่ APNS รองรับได้ที่การอ้างอิงคีย์เพย์โหลดของ Apple