تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

الاسم

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

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

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

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

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

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

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

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

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