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

تحتوي كل إضافة دولية على ملف واحد على الأقل باسم messages.json يوفّر سلاسل خاصة باللغة. تصف هذه الصفحة تنسيق ملفات 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" و"مرحبًا" و"إلى اللقاء":

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. للحصول على تفاصيل حول كيفية استخدام ملف الرسائل، على سبيل المثال، ما يحدث عندما لا تحدّد اللغة جميع الرسائل، يمكنك الاطّلاع على الانتشار على نطاق عالمي.

اسم

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

يُعد الاسم مفتاحًا غير حساس لحالة الأحرف، ويتيح لك استرداد نص الرسالة المترجَمة. يمكن أن يتضمن الاسم الأحرف التالية:

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

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

messages.json:

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

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

رسالة

الرسالة المترجمة، في شكل سلسلة يمكن أن تحتوي على placeholders. استخدِم $_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$ هي الطريقة المفضّلة للإشارة إلى السلاسل البديلة
(السلاسل المحدَّدة باستخدام المَعلمة الاستبدالات في i18n.getMessage)، يمكنك أيضًا الرجوع
إلى السلاسل البديلة مباشرةً داخل الرسالة. على سبيل المثال، تشير الرسالة التالية إلى أول ثلاث سلاسل بديلة تم تمريرها إلى getMessage():



messages.json:


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



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



الوصف



اختيارية. تمثّل هذه السمة وصفًا للرسالة بهدف تقديم سياق أو تفاصيل لمساعدة المترجم في تقديم أفضل ترجمة ممكنة.



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



messages.json:


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



placeholders



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



    

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

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




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



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



مَعلمة subsformsالقيمة 1 دولار أمريكيالقيمة 2 دولار أمريكي (أو ما يعادله بالعملة المحلية)القيمة 3 دولار أمريكي
userNameقيمة userName""""
["Cira", "Kathy"]"Cira""Kathy"""



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



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



messages.json:


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