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

توضّح هذه المستندات استخدام حقول الأقلمة في 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

• توطين تطبيقك - مطوّرو برامج Android

إعداد iOS

تحديد موارد السلاسل النصية: حدِّد السلاسل الأساسية في ملف Localizable.strings (عادةً في مجلد Base.lproj أو في String Catalog). استخدِم محدّدات التنسيق (%@ و%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 %@.";

لمزيد من المعلومات، يمكنك الاطّلاع على المستندات التالية:

• Localization - Apple Developer Documentation

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

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

عند إرسال الإشعار باستخدام واجهة برمجة التطبيقات FCM HTTP v1 API، ينشئ الخادم حمولة واحدة تستخدم مفاتيح الموارد (*_loc_key) والبيانات الديناميكية (*_loc_args) كمصفوفة من السلاسل.

مثال على حمولة الإصدار الأول من HTTP في 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.