本地化訊息格式

每個國際化擴充功能或應用程式至少有一個名為 messages.json 的檔案，提供特定語言代碼的字串。本頁面說明 messages.json 檔案的格式。如要瞭解如何進行國際化和本地化，請參閱「國際化」頁面。

欄位摘要

以下程式碼顯示 messages.json 支援的欄位。只需要「name」和「message」欄位。

{
  "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."
      },
      ...
    }
  },
  ...
}

範例

以下是定義三個訊息 (分別命名為「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 檔案中可能出現的每個欄位。如要進一步瞭解如何使用 messages 檔案 (例如，當語言代碼未定義所有訊息時會發生什麼情況)，請參閱「國際化」。

名稱

其實沒有名為「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 $$)"


Although placeholders such as $USER$ are the preferred way of referring to substitution strings
(strings specified using the substitutions parameter of i18n.getMessage) you can also refer
to substitution strings directly within the message. For example, the following message refers to
the first three substitution strings passed into getMessage():


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



Despite that example, we recommend that you stick to using placeholders instead of $_n_ strings
within your messages. Think of placeholders as good variable names. A week after you write your
code, you'll probably forget what $1 refers to, but you'll know what your placeholders refer to.
For more information on placeholders and substitution strings, see the placeholders section.



description



Optional. A description of the message, intended to give context or details to help the translator
make the best possible translation.



Here are three examples of descriptions, taken from the Example section:


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



placeholders



Optional. Defines one or more substrings to be used within the message. Here are two reasons you
might want to use a placeholder:



    

  • To define the text for a part of your message that shouldn't be translated. Examples: HTML code,
trademarked names, formatting specifiers.
    • 

  • To refer to a substitution string passed into getMessage(). Example: $1.
    • 




Each placeholder has a name, a "content" item, and an optional "example" item. A placeholder's name
is case-insensitive and can contain the same characters as a message name.



The "content" item's value is a string that can refer to substitution strings, which are specified
using the i18n.getMessage method's substitutions parameter. The value of a "content" item is
typically something like "Example.com" or "$1". If you refer to a substitution string that doesn't
exist, you get an empty string. The following table shows how $_n_ strings correspond to strings
specified by the substitutions parameter.



substitutions parameterValue of $1Value of $2Value of $3
userNamevalue of userName""""
["Cira", "Kathy"]"Cira""Kathy"""



The "example" item (optional, but highly recommended) helps translators by showing how the content
appears to the end user. For example, a placeholder for a dollar amount should have an example like
"$23.45".



The following snippet, taken from the Example section, shows a "placeholders" item that
contains two placeholders named "our_site" and "user". The "our_site" placeholder has no "example"
item because its value is obvious from the "content" field.


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