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

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

ملخّص الحقل

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

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":

messages.json:

{
  "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". اسم هذا الحقل هو اسم الرسالة — وهو نفسه name الذي تراه في __MSG__name___ أو getMessage("_name_").

الاسم هو مفتاح غير حسّاس لحالة الأحرف يتيح لك استرداد نص الرسالة المترجَمة. يمكن للاسم تتضمن الأحرف التالية:

  • A-Z
  • a-z
  • 0-9
  • _ (شرطة سفلية)
  • @

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

messages.json:

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

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

رسالة

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

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

messages.json:

"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 $):

messages.json:

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

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



messages.json:


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



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



الوصف



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



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



messages.json:


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



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



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



    

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

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




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



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



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



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



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



messages.json:


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