每個國際化擴充功能都至少有一個名為 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"
}
}