แปลข้อความ

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

ภาพรวมการแปลเป็นภาษาท้องถิ่นFCM

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

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

ช่อง FCM	คำอธิบาย	การดำเนินการของไคลเอ็นต์
title_loc_key	คีย์สำหรับสตริงชื่อในการแปลทรัพยากรสตริงของแอปไคลเอ็นต์	ระบบปฏิบัติการจะค้นหาสตริงที่เกี่ยวข้องในไฟล์ที่แปลเป็นภาษาท้องถิ่นของแอป
body_loc_key	คีย์สำหรับสตริงเนื้อหาในการแปลทรัพยากรสตริงของแอปไคลเอ็นต์	ระบบปฏิบัติการจะค้นหาสตริงที่เกี่ยวข้องในไฟล์ที่แปลเป็นภาษาท้องถิ่นของแอป
title_loc_args	อาร์เรย์ของค่าสตริงแบบไดนามิกที่จะแทนที่ลงในสตริง title_loc_key	ระบบปฏิบัติการจะแทรกอาร์กิวเมนต์เหล่านี้ลงในตัวระบุรูปแบบของสตริงที่แปลเป็นภาษาท้องถิ่น
body_loc_args	อาร์เรย์ของค่าสตริงแบบไดนามิกที่จะแทนที่ลงในสตริง body_loc_key	ระบบปฏิบัติการจะแทรกอาร์กิวเมนต์เหล่านี้ลงในตัวระบุรูปแบบของสตริงที่แปลเป็นภาษาท้องถิ่น

ขั้นตอนที่ 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 (หรือเพิ่ม การแปลเป็นภาษาท้องถิ่นโดยใช้แคตตาล็อกสตริง) และแปลคีย์

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

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

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

• การแปลเป็นภาษาท้องถิ่น - เอกสารประกอบสำหรับนักพัฒนาแอปของ Apple

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

ขั้นตอนที่ 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" ในตัวอย่าง) ตัวจัดรูปแบบสตริงของระบบปฏิบัติการไคลเอ็นต์จะจัดการการแปลงประเภทขั้นสุดท้ายตามตัวระบุรูปแบบ (%ld หรือ %1$d)

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

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

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

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

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

ภาษาของอุปกรณ์	title_loc_key: welcome_title	title_loc_args: ["Alice"]	ชื่อที่แสดงสุดท้าย
อังกฤษ	"Welcome, %1$s!"	Alice	"Welcome, Alice!"
ฝรั่งเศส	"Bienvenue, %1$s!"	Alice	"Bienvenue, Alice!"
เยอรมัน	"Willkommen, %1$s!"	Alice	"Willkommen, Alice!"

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

ตัวอย่าง: ข้อความแจ้งเตือนพร้อมตัวเลือกการแปลเป็นภาษาท้องถิ่น

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

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

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