本地化訊息格式

每個國際化擴充功能或應用程式都有至少一個名為 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."
      },
      ...
    }
  },
  ...
}

範例

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

名稱

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

雖然 $USER$ 等預留位置是參照替換字串 (使用 i18n.getMessage 的 substitutions 參數指定的字串) 的首選方式，但您也可以直接在訊息中參照替換字串。例如，以下訊息是傳遞至 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。
    • 




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



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



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



「示例」項目 (選用，但強烈建議使用) 可向譯者顯示內容在使用者端的顯示方式，協助他們進行翻譯。舉例來說，美元金額的預留位置應使用 "$23.45" 做為示例。



以下程式碼片段取自「範例」一節，顯示「預留位置」項目，其中包含兩個名為「our_site」和「user」的預留位置。「our_site」預留位置沒有「example」項目，因為其值很容易在「content」欄位中。


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