本地化訊息格式

每個國際化擴充功能或應用程式都有至少一個名為 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」和 「再見」：

{
  "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 美元的價值
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"
  }
}