本地化訊息格式

每個國際化副檔名都有至少一個名為 messages.json 的檔案，提供 特定語言代碼的字串本頁說明 messages.json 檔案格式。如需深入瞭解 若想瞭解如何國際化和本地化，請參閱國際化頁面。

欄位摘要

以下程式碼顯示 messages.json 的支援欄位。只有「name」以及「message」訊息 所有必填欄位。

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」和 「再見」：

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」欄位。這個欄位的名稱是訊息名稱，也就是您在 __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$ 等預留位置是參照替換字串 (使用 i18n.getMessage 的 substitutions 參數指定的字串) 的首選方式，但您也可以直接在訊息中參照替換字串。舉例來說，下列訊息指的是
前三個傳遞至 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。
    • 




每個預留位置都有名稱、「內容」項目和選用的「範例」項目。預留位置名稱不區分大小寫，且可以包含與訊息名稱相同的字元。



「內容」項目的值是字串，可參照替換字串，而替換字串會使用 i18n.getMessage 方法的 substitutions 參數指定。「內容」的值項目是
例如「Example.com」或「$1」。如果您參照的替換字串不存在，您會收到空白字串。下表顯示 $_n_ 字串如何對應至字串
由 substitutions 參數指定。



substitutions 參數價值 $1$2 美元的價值價值 $3 美元
userNameuserName 的值""""
["Cira", "Kathy"]"Cira""Kathy"""



「範例」項目 (選用，但強烈建議使用) 呈現內容
使用者會看到的文字舉例來說，美元金額的預留位置應使用 "$23.45" 做為示例。



下列程式碼片段取自「示例」部分，其中顯示「預留位置」CANNOT TRANSLATE
包含兩個名為「our_site」的預留位置和「user」「our_site」placeholder 不含「example」
因為其值很容易在「content」] 欄位。



messages.json:


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