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

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

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 Developers

• התאמה לשוק המקומי של האפליקציה – Android Developers

הגדרת 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 %@.";

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

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

• String resources - Apple Developer Documentation

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

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

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

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

• הסדר חשוב: המחרוזות ב-*_loc_args צריכות להיות בדיוק בסדר שנדרש על ידי placeholders בקובץ משאבי המחרוזות (למשל, %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. שם מפורטים כל המפתחות שזמינים בבלוקים ספציפיים לפלטפורמה בגוף ההודעה. לרשימת המפתחות שנתמכים על ידי APNS, אפשר לעיין במאמר של אפל בנושא הפניה למפתחות של מטען ייעודי (Payload).