התאמת ההודעות לשוק המקומי

במסמך הזה מוסבר איך להשתמש בשדות הלוקליזציה של FCM (*_loc_key ו-*_loc_args) כדי לשלוח התראות שמותאמות באופן אוטומטי להגדרות השפה של המשתמש ב-Android וב-iOS. כך השרת יכול לשלוח מטען ייעודי (payload) אחד, ללא קשר לשפה, ולהעביר את התרגום למכשיר הלקוח.

FCM סקירה כללית על לוקליזציה

כדי להתאים את האפליקציה לשוק המקומי, אתם יכולים לשלוח מפתח שתואם לרשומה של משאב מחרוזת בתוך האפליקציה של המשתמש. מערכת ההפעלה של המכשיר מטפלת בחיפוש ובהוספה של ארגומנטים דינמיים.

שלב 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 %@.";

מידע נוסף זמין במשאבי העזרה הבאים:

• התאמה לשוק המקומי – מאמרי עזרה למפתחים של אפל

• משאבי מחרוזות – מאמרי העזרה למפתחים של אפל

שלב 2: יצירת המטען הייעודי (payload) של ההודעה ב-FCM

כששולחים את ההתראה באמצעות FCM HTTP v1 API, השרת יוצר מטען ייעודי (payload) אחד שמשתמש במפתחות המשאבים (*_loc_key) ובנתונים הדינמיים (*_loc_args) כמערך של מחרוזות.

מטען ייעודי (payload) לדוגמה של 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"]
          }
        }
      }
    }
  }
}

נקודות מרכזיות לגבי ארגומנטים של מטען ייעודי (payload)

• הסדר חשוב: המחרוזות ב-*_loc_args צריכות להיות בסדר המדויק שנדרש על ידי הפלייסהולדרים בקובץ משאבי המחרוזות (למשל, %1$s, %2$s).

• מחרוזות בלבד: כל הרכיבים במערך *_loc_args חייבים להיות מחרוזות, גם אם הם מייצגים מספרים (כמו "3" בדוגמה). מעצב המחרוזות של מערכת ההפעלה של הלקוח מטפל בהמרה הסופית של הסוג על סמך מפרט הפורמט (%ld או %1$d).

שלב 3: עיבוד והצגה בצד הלקוח

כשהמכשיר מקבל את ההתראה, הפעולות הבאות מתרחשות באופן אוטומטי:

1. בדיקת שפה: המכשיר מזהה את הלוקאל הראשי של המשתמש (למשל, גרמנית, איטלקית).

2. חיפוש מפתח: מערכת ההפעלה משתמשת בערך *_loc_key (welcome_title) כדי לחפש את המחרוזת המתורגמת המתאימה בקובצי המשאבים של האפליקציה, בהתאם ללוקאל של המכשיר.

3. הוספת ארגומנט: מערכת ההפעלה לוקחת את המערך מ-*_loc_args (["Alice"]) ומכניסה את הערכים למחרוזת המותאמת לשוק המקומי, בהתאם לכללי העיצוב של הלוקאל (סימני פיסוק, סדר המילים וכו').

התהליך הזה מבטיח שכל משתמש יקבל הודעה שמותאמת להעדפות השפה שלו, עם המבנה הלשוני הנכון, תוך שמירה על מטען ייעודי (payload) סטנדרטי מהשרת שלכם.

דוגמה: הודעה עם אפשרויות לוקליזציה

בקשת השליחה שבדוגמה הבאה שולחת התראה לנושא 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, שבהם מפורטים כל המפתחות שזמינים בבלוקים ספציפיים לפלטפורמה בגוף ההודעה. במסמך העזר של אפל בנושא מפתחות מטען ייעודי (payload) מפורטים המפתחות שנתמכים על ידי APNS.