本地化消息格式

每个国际化扩展程序至少有一个名为 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

抱歉,根本不存在名为“name”的字段。此字段的名称是消息的名称,与您在 __MSG__name___getMessage("_name_") 中看到的名称相同。

该名称是一个不区分大小写的键,可让您检索本地化的消息文本。名称可以包含以下字符:

  • 名称首字母(升序)
  • 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 substitutions 参数指定的字符串),但您也可以直接在消息中引用替换字符串。例如,以下消息表示传入 getMessage() 的前三个替代字符串:



messages.json:



尽管如此,我们还是建议您坚持在消息中使用占位符,而不是 $_n_ 字符串。将占位符视为好的变量名称。编写代码一周后,您可能会忘记 $1 指代什么,但会知道占位符所指什么。如需详细了解占位符和替换字符串,请参阅placeholders部分。



说明



可选。消息的说明,旨在提供上下文或详细信息,以帮助译者做出最佳翻译。



以下是摘自示例部分的说明的三个示例:



messages.json:



placeholders



可选。定义要在消息中使用的一个或多个子字符串。以下是需要使用占位符的两个原因:




  • 定义消息中不应翻译的部分的文本。示例:HTML 代码、商标名称、格式说明符。

  • 引用传入 getMessage() 的替代字符串。示例:$1



每个占位符都有一个名称、一个“content”项和一个可选的“example”项。占位符的名称不区分大小写,可包含与消息名称相同的字符。



content”项的值是一个字符串,可以引用替换字符串,这些字符串使用 i18n.getMessage 方法的 substitutions 参数指定。“content”项的值通常类似于“Example.com”或“$1”。如果您引用的替换字符串不存在,则会获得一个空字符串。下表显示了 $_n_ 字符串如何与 substitutions 参数指定的字符串相对应。



substitutions 参数1 美元2 美元的价值价值 3
userNameuserName”的值""""
["Cira", "Kathy"]"Cira""Kathy"""


“示例”项(可选,但强烈推荐)可通过向最终用户展示内容的方式,帮助翻译人员。例如,美元金额的占位符应具有类似 "$23.45" 的示例。



以下代码段取自示例部分,显示了一个“占位符”项,其中包含两个名为“our_site”和“user”的占位符。“our_site”占位符没有“example”项,因为它的值从“content”字段中很明显。



messages.json: