فرمت های پیام محلی سازی

هر برنامه یا برنامه افزودنی بین‌المللی حداقل یک فایل به نام 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_") می بینید.

نام یک کلید حساس به حروف کوچک و بزرگ است که به شما امکان می دهد متن پیام محلی را بازیابی کنید. نام می تواند شامل کاراکترهای زیر باشد:

  • AZ
  • az
  • 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$ روش ترجیحی برای ارجاع به رشته‌های جایگزین هستند (رشته‌هایی که با استفاده از پارامتر جایگزینی 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" رشته ای است که می تواند به رشته های جایگزینی اشاره داشته باشد که با استفاده از پارامتر جایگزینی روش i18n.getMessage مشخص شده اند. مقدار یک آیتم "محتوا" معمولا چیزی شبیه "Example.com" یا "$1" است. اگر به رشته جایگزینی مراجعه کنید که وجود ندارد، یک رشته خالی دریافت می کنید. جدول زیر نشان می دهد که چگونه رشته های $_n_ با رشته های مشخص شده توسط پارامتر جایگزینی مطابقت دارند.

پارامتر جایگزینی ارزش 1 دلار ارزش 2 دلار ارزش 3 دلار
userName مقدار userName "" ""
["Cira", "Kathy"] "Cira" "Kathy" ""

مورد "مثال" (اختیاری، اما به شدت توصیه می شود) با نشان دادن نحوه نمایش محتوا به کاربر نهایی به مترجمان کمک می کند. برای مثال، یک جای‌بان برای مقدار دلار باید مثالی مانند "$23.45" داشته باشد.

قطعه زیر که از بخش Example گرفته شده است، یک آیتم "placeholders" را نشان می دهد که شامل دو مکان نگهدار به نام های "our_site" و "user" است. مکان‌نمای "our_site" مورد "مثالی" ندارد زیرا مقدار آن از قسمت "محتوا" مشخص است.

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