أقلمة الرسائل

توضّح هذه الوثائق كيفية استخدام حقول تحديد الموقع الجغرافي FCM (*_loc_key و*_loc_args) لعرض إشعارات تتكيّف تلقائيًا مع إعدادات لغة المستخدم على Android وiOS. يتيح ذلك لخادمك إرسال حمولة واحدة غير مرتبطة بلغة معيّنة، مع تفويض عملية الترجمة إلى جهاز العميل.

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

لمزيد من المعلومات، يُرجى الرجوع إلى المستندات التالية:

• تحديد الموقع الجغرافي - مستندات Apple للمطوّرين

• مصادر السلاسل - مستندات Apple للمطوّرين

الخطوة 2: إنشاء حمولة رسالة FCM

عند إرسال الإشعار باستخدام FCM HTTP v1 API، ينشئ خادمك حمولة واحدة تستخدم مفاتيح المصادر (*_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 المرجعية لمفاتيح الحمولة .