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

במסמך הזה מוסבר איך להשתמש בשדות לוקליזציה 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 %@.";

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

• Localization - Apple Developer Documentation

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

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

• הסדר חשוב: המחרוזות ב-*_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) של אפל.