格式:区域特定的消息

每一个具有国际化支持的扩展程序或应用至少有一个名为 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.getMessagesubstitutions 参数中指定的字符串)的推荐方式,但是您也可以直接在消息中引用替代字符串。例如,如下消息引用传递给 getMessage()的前三个替代字符串:

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

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

description

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

如下是描述的三个例子,来自例子部分:

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

placeholders

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

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

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

"content" 项的值为一字符串,用于引用 i18n.getMessagesubstitutions 参数中指定的替代字符串。"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"
  }
}