格式：区域特定的消息

每一个具有国际化支持的扩展程序或应用至少有一个名为 messages.json 的文件，提供区域特定的字符串。这一页面描述了 messages.json 文件的格式。有关如何添加国际化支持以及如何本地化的更多内容，请参见国际化支持页面。

字段概述

如下代码展示了 messages.json 支持的字段，只有 "name" 和 "message" 字段是必需的。

{
  "name": {
    "message": "消息文本，可以包含可选的占位符。",
    "description": "帮助翻译者的消息描述。",
    "placeholders": {
      "placeholder_name": {
        "content": "放在消息中的字符串。",
        "example": "帮助翻译者的占位符字符串举例。"
      },
      ...
    }
  },
  ...
}

例子

如下是一个 messages.json 文件，定义了三个消息，名称分别为 "prompt_for_name"、"hello" 和 "bye"：

{
  "prompt_for_name": {
    "message": "您叫什么名字？",
    "description": "询问用户的姓名"
  },
  "hello": {
    "message": "$USER$，您好！",
    "description": "向用户打招呼",
    "placeholders": {
      "user": {
        "content": "$1",
        "example": "Cira"
      }
    }
  },
  "bye": {
    "message": "$USER$，再见。欢饮再次光临 $OUR_SITE$！",
    "description": "向用户道别",
    "placeholders": {
      "our_site": {
        "content": "Example.com",
      },
      "user": {
        "content": "$1",
        "example": "Cira"
      }
    }
  }
}

字段详情

这一部分描述了可以出现在 messages.json 文件中的各个字段。有关如何使用消息文件，例如某种语言没有定义所有消息的情况下如何处理，请参见国际化支持。

name

事实上，没有字段名为 "name"，该字段的名称即消息的名称——与您在 __MSG_name__ 或 getMessage("name") 中看到的是同一个名称。 名称不区分大小写，通过它使您获得本地化的消息文本。名称可以包含下列字符：

名称是一个不区分大小写的键，通过它使您获得本地化消息的文本。名称可以包含下列字符：

• A-Z
• a-z
• 0-9
• _（下划线）
• @

注意：不要定义以“@@”开头的名称，这些名称保留给预定义消息使用。

如下是名称的三个例子，来自例子部分：

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

有关使用名称的更多例子，请参见国际化支持页面。

message

经过翻译的消息，以字符串形式表示，可以包含占位符。使用 $占位符名称$（不区分大小写）引用某个占位符。例如，您可以引用名为 "our_site" 的占位符：$our_site$、$OUR_SITE$ 或 $oUR_sITe$。

如下是消息的三个例子，来自例子部分：

"message": "您叫什么名字？"
...
"message": "$USER$，您好！"
...
"message": "$USER$，再见。欢饮再次光临 $OUR_SITE$！"

如果要在字符串中使用半角美元符号（$），请使用 $$。例如，使用如下代码指定消息金额 $：

"message": "金额 $$"

尽管诸如 $USER$ 这样的占位符是引用替代字符串（在 i18n.getMessage 的 substitutions 参数中指定的字符串）的推荐方式，但是您也可以直接在消息中引用替代字符串。例如，如下消息引用传递给 getMessage()的前三个替代字符串：

"message": "参数：$1, $2, $3"

尽管给出了这样的例子，但我们仍然推荐您在消息中坚持使用占位符，而不是 $n 字符串。把占位符看作是好的变量名，您编写完代码的一周后，您可能会忘记 $1 引用什么，但是您知道您的占位符引用什么。有关占位符以及替代字符串的更多信息，请参见占位符部分。

description

可选。消息的描述，用于向翻译者提供语境或细节，以便作出最好的翻译。

如下是描述的三个例子，来自例子部分：

"description": "询问用户的姓名"
...
"description": "向用户打招呼"
...
"description": "向用户道别"

placeholders

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

• 定义文本，用于您消息中不应该翻译的部分。例如：HTML 代码、商标名称、格式化指示符等。
• 引用传递给 getMessage() 的字符串，例如：$1。

每一个占位符都有名称以及 "content" 项，以及可选的 "example" 项。占位符的名称不分大小写，可以包含的字符与消息名称相同。

"content" 项的值为一字符串，用于引用 i18n.getMessage 的 substitutions 参数中指定的替代字符串。"content" 项的值通常为 "Example.com" 或 "$1" 等。如果您引用了不存在的替代字符串，您将得到空字符串。下表显示 $n 字符串如何对应 substitutions 参数中指定的字符串。

substitutions 参数	$1 的值	$2 的值	$3 的值
userName	userName 的值	""	""
["Cira", "Kathy"]	"Cira"	"Kathy"	""

"example" 项（可选，但强烈建议使用）显示内容将如何展现给最终用户，有助于翻译者。例如，用于美元金额的占位符应该具有 "example" 属性值 "$23.45"。

来自例子部分的如下片段展示了一个 "placeholders" 项，包含两个占位符，分别名为 "our_site" 和 "user"。"our_site" 占位符没有 "example" 属性，因为它的值从 "content" 属性中可以明显看出。

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