تنسيقات رسائل الأقلمة

تحتوي كل إضافة أو تطبيق متوافقَين مع لغات متعددة على ملف واحد على الأقل باسم messages.json يقدّم سلاسل خاصة باللغة. توضّح هذه الصفحة تنسيق ملفات messages.json. للحصول على معلومات عن كيفية النشر على نطاق عالمي والأقلمة، يُرجى الاطّلاع على صفحة النشر على نطاق عالمي.

ملخّص الحقل

يعرض الرمز التالي الحقول المتوافقة مع messages.json. لا يُشترط سوى حقلَي "الاسم" و"الرسالة" .

{
  "name": {
    "message": "Message text, with optional placeholders.",
    "description": "Translator-aimed description of the message.",
    "placeholders": {
      "placeholder_name": {
        "content": "A string to be placed within the message.",
        "example": "Translator-aimed example of the placeholder string."
      },
      ...
    }
  },
  ...
}

مثال

في ما يلي ملف messages.json يحدّد ثلاث رسائل باسم "prompt_for_name" و"hello" و "bye":

{
  "prompt_for_name": {
    "message": "What's your name?",
    "description": "Ask for the user's name"
  },
  "hello": {
    "message": "Hello, $USER$",
    "description": "Greet the user",
    "placeholders": {
      "user": {
        "content": "$1",
        "example": "Cira"
      }
    }
  },
  "bye": {
    "message": "Goodbye, $USER$. Come back to $OUR_SITE$ soon!",
    "description": "Say goodbye to the user",
    "placeholders": {
      "our_site": {
        "content": "Example.com",
      },
      "user": {
        "content": "$1",
        "example": "Cira"
      }
    }
  }
}

تفاصيل الحقل

يصف هذا القسم كل حقل يمكن أن يظهر في ملف messages.json. للحصول على تفاصيل حول كيفية يتم استخدام ملف الرسائل - على سبيل المثال، ما يحدث عندما لا تحدد لغة جميع الرسائل - راجع نشر الفيديو على نطاق عالمي:

الاسم

في الواقع، لا يتوفّر حقل باسم "name". اسم هذا الحقل هو اسم الرسالة، وهو الاسم نفسه الذي يظهر لك في __MSG__name___ أو getMessage("_name_").

والاسم هو مفتاح غير حساس لحالة الأحرف يسمح لك باسترداد نص الرسالة المترجَم. يمكن أن يحتوي الاسم على الشخصيات التالية:

  • A-Z
  • a-z
  • 0-9
  • _ (شرطة سفلية)
  • @
ملاحظة: لا تحدِّد أسماء تبدأ بـ "@@"، فهذه الأسماء محجوزة للرسائل المحدّدة مسبقًا.

إليك ثلاثة أمثلة للأسماء، مأخوذة من القسم مثال:

"prompt_for_name": {
  ...
},
"hello": {
  ...
},
"bye": {
  ...
}

للاطلاع على مزيد من الأمثلة على استخدام الأسماء، راجع صفحة الانتشار على نطاق عالمي.

رسالة

الرسالة المترجَمة، في شكل سلسلة يمكن أن تحتوي على عناصر نائبة استخدِم $_placeholder_name_$ (لا تُراعي حالة الأحرف) للإشارة إلى عنصر نائب معيّن. على سبيل المثال، يمكنك الإشارة إلى عنصر نائب باسم "our_site" باسم $our_site$ أو $OUR_SITE$ أو $oUR_sITe$.

في ما يلي ثلاثة أمثلة على الرسائل، مأخوذة من قسم مثال:

"message": "What's your name?"
...
"message": "Hello, $USER$"
...
"message": "Goodbye, $USER$. Come back to $OUR_SITE$ soon!"

لإضافة علامة الدولار ($) إلى السلسلة، استخدِم $$. For example, use the following code to specify the message Amount (in $):

"message": "Amount (in $$)"
.

على الرغم من أنّ العناصر النائبة، مثل $USER$، هي الطريقة المفضّلة للإشارة إلى سلاسل الاستبدال
(سلاسل محدّدة باستخدام المَعلمة substitutions في i18n.getMessage)، يمكنك أيضًا الإشارة
إلى سلاسل الاستبدال مباشرةً في الرسالة. على سبيل المثال، تشير الرسالة التالية إلى
تم تمرير سلاسل الاستبدال الثلاث الأولى إلى getMessage():


"message": "Params: $1, $2, $3"



على الرغم من هذا المثال، ننصحك باستخدام العناصر النائبة بدلاً من سلاسل $_n_
في رسائلك. فكر في العناصر النائبة على أنها أسماء متغيرات جيدة. بعد أسبوع من كتابة
الرمز، من المحتمل أن تنسى ما يشير إليه الرمز $1، ولكنك ستعرف ما يشير إليه العنصر النائب.
لمزيد من المعلومات عن العناصر النائبة وسلاسل الاستبدال، يُرجى الاطّلاع على قسم العناصر النائبة.



الوصف



اختياري وصف للرسالة، يهدف إلى تقديم سياق أو تفاصيل لمساعدة المترجم في تقديم أفضل ترجمة ممكنة



إليك ثلاثة أمثلة للأوصاف مأخوذة من القسم مثال:


"description": "Ask for the user's name"
...
"description": "Greet the user"
...
"description": "Say goodbye to the user"



العناصر النائبة



اختياري تُحدِّد سلسلة فرعية واحدة أو أكثر لاستخدامها في الرسالة. إليك سببين
قد ترغب في استخدام عنصر نائب:



    

  • لتحديد نص جزء من رسالتك لا يجب ترجمته. أمثلة: رمز HTML،
والأسماء المسجّلة كعلامات تجارية، ومُحدّدات التنسيق
    • 

  • للإشارة إلى سلسلة بديل تم تمريرها إلى getMessage(). مثال: $1
    • 




يحتوي كل عنصر نائب على اسم وعنصر "محتوى" وعنصر "مثال" اختياري. اسم العنصر النائب
هو غير حسّاس لحالة الأحرف ويمكن أن يحتوي على الأحرف نفسها الواردة في اسم الرسالة.



"المحتوى" قيمة العنصر هي سلسلة يمكن أن تشير إلى سلاسل الاستبدال التي يتم تحديدها
باستخدام معلمة الاستبدالات لطريقة i18n.getMessage. تكون قيمة عنصر "المحتوى" عادةً مماثلة لـ "Example.com" أو "1 ريال سعودي". إذا كنت تشير إلى سلسلة استبدال لا
الموجودة، فستحصل على سلسلة فارغة. يوضّح الجدول التالي كيفية مطابقة سلاسل $_n_ لسلاسل
حدّدتها المَعلمة الاستبدالات.



مَعلمة substitutionsالقيمة 1 دولار أمريكيالقيمة 2 دولار أمريكيالقيمة 3 دولار أمريكي
userNameقيمة userName""""
["Cira", "Kathy"]"Cira""Kathy"""



يساعد عنصر "المثال" (اختياري، ولكن يُنصح به بشدة) المترجمين من خلال عرض كيفية
ظهور المحتوى للمستخدم النهائي. على سبيل المثال، يجب أن يتضمّن العنصر النائب لمبلغ بالدولار الأمريكي مثالاً مثل
"$23.45".



يعرض المقتطف التالي، المأخوذ من قسم مثال، عنصر "العناصر النائبة" الذي يحتوي على عنصرَين نائبَين باسمَي "our_site" و"user". يحتوي "our_site" لا يحتوي العنصر النائب على "example"
العنصر لأن قيمته واضحة من "المحتوى" .


"placeholders": {
  "our_site": {
    "content": "Example.com",
  },
  "user": {
    "content": "$1",
    "example": "Cira"
  }
}