本地化消息格式

每个经过国际化处理的扩展程序或应用都至少有一个名为 messages.json 的文件，用于提供特定于语言区域的字符串。本页面介绍了 messages.json 文件的格式。如需了解如何国际化和本地化，请参阅国际化页面。

字段摘要

以下代码显示了 messages.json 支持的字段。只有“name”和“message”字段是必填字段。

{
  "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”的消息：

{
  "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
  • a-z
  • 0-9
  • _（下划线）
  • @
注意：请勿定义以“@@”开头的名称。这些名称已预留给预定义消息。

以下是 Example 部分中的三个名称示例：

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

如需查看使用姓名的更多示例，请参阅国际化页面。

消息

翻译后的消息（采用可包含占位符的字符串形式）。使用 $_placeholder_name_$（不区分大小写）来引用特定占位符。例如，您可以将名为“our_site”的占位符引用为 $our_site$、$OUR_SITE$ 或 $oUR_sITe$。

以下是摘自示例部分的三个消息示例：

"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 $):

"message": "Amount (in $$)"


虽然 $USER$ 等占位符是引用替换字符串（使用 i18n.getMessage 的 substitutions 参数指定的字符串）的首选方式，但您也可以直接在消息中引用替换字符串。例如，以下消息引用了传入 getMessage() 的前三个替换字符串：


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



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



说明



可选。邮件的说明，旨在提供背景信息或详细信息，以帮助译者尽可能提供最准确的译文。



以下是三个说明示例，摘自示例部分：


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



占位符



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



    

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

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




每个占位符均包含名称、“内容”项和可选的“示例”项。占位符的名称不区分大小写，可以包含与消息名称相同的字符。



“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”占位符没有“示例”项，因为其值从“content”字段中很明显。


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