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

توضّح هذه المستندات كيفية استخدام حقول 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 أو "كتالوج السلاسل"). استخدِم محدّدات التنسيق (%@ و%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 Developer

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

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

مثال على حمولة FCM HTTP الإصدار 1

يتم وضع مفاتيح الترجمة داخل كتل الإلغاء الخاصة بالنظام الأساسي (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 الإصدار 1 للحصول على تفاصيل كاملة حول المفاتيح المتاحة في الحقول الخاصة بالمنصة في نص الرسالة. للاطّلاع على المفاتيح المتوافقة مع APNS، يُرجى الرجوع إلى مرجع مفتاح الحمولة من Apple.