แปลข้อความ

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

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

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

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

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

• String resources - Apple Developer Documentation

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

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

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

คีย์การแปลภาษาจะอยู่ในบล็อกการลบล้างเฉพาะแพลตฟอร์ม (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"]) และแทรกค่าลงในสตริงที่แปลแล้ว โดยเป็นไปตามกฎการจัดรูปแบบของภาษา (เครื่องหมายวรรคตอน ลำดับคำ ฯลฯ)

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

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

คำขอส่งตัวอย่างต่อไปนี้จะส่งการแจ้งเตือนไปยังหัวข้อ 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