本地化訊息格式

每個國際化擴充功能都至少有一個名為 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」和「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 檔案可以顯示的每個欄位。如要進一步瞭解訊息檔案的使用方式 (例如語言代碼未定義所有訊息時會發生什麼事)，請參閱「國際化」一文。

名稱

其實沒有名為「name」的欄位。這個欄位的名稱是訊息的名稱，即與您在 __MSG__name___ 或 getMessage("_name_") 中看到的 name 相同。

名稱是不區分大小寫的鍵，可讓您擷取本地化訊息文字。名稱可包含下列字元：

  • A 至 Z
  • a-z
  • 0-9
  • _ (底線)
  • @

以下是三個取自「範例」部分的名稱範例：

messages.json:

"prompt_for_name": {
  ...
},
"hello": {
  ...
},
"bye": {
  ...
}

如需更多名稱的使用範例，請參閱國際化頁面。

訊息

翻譯後的訊息，採用可包含placeholders的字串格式。使用 $_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 的替代字串參數指定字串)，但您也可以直接在訊息中參照替代字串。舉例來說，下列訊息是指傳入 getMessage() 的前三個替換字串：



messages.json:


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



儘管如此，我們還是建議您繼續在訊息中使用預留位置，而非 $_n_ 字串。你可以將預留位置視為良好的變數名稱。編寫程式碼一週後，您可能會忘記 $1 參照的參照，但仍會知道預留位置代表的意義。如要進一步瞭解預留位置和替換字串，請參閱placeholders一節。



description



選用。訊息的說明，旨在提供背景資訊或詳細資訊，協助譯者提供最佳翻譯。



以下是三個取自「範例」部分的說明範例：



messages.json:


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



placeholders



選用。定義要在訊息中使用的一或多個子字串。以下兩個原因建議使用預留位置：



    

  • 定義不需翻譯的郵件部分文字。例如 HTML 程式碼、商標名稱、格式指定碼。
    • 

  • 參照傳入 getMessage() 的替換字串。例如：$1.
    • 




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



「content」項目值是一個字串，可參照替代字串，這些字串使用 i18n.getMessage 方法的 substitutions 參數指定。「content」項目的值通常類似「Example.com」或「$1」。如果您參照的替換字串不存在，就會獲得空字串。下表顯示 $_n_ 字串如何對應到 substitutions 參數指定的字串。



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



「範例」項目 (非必要，但強烈建議填寫) 會顯示內容向使用者顯示的方式，讓譯者參考。例如，金額的預留位置應像 "$23.45" 這樣一樣。



以下從範例區段擷取的程式碼片段顯示了包含兩個名為「our_site」和「user」的預留位置的「placeholders」項目。「our_site」預留位置沒有「example」項目，因為其值明顯顯示在「content」欄位中。



messages.json:


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