本地化消息格式

每个国际化扩展程序都至少有一个名为 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
  • a-z
  • 0-9
  • _（下划线）
  • @

以下是摘自示例部分的三个名称示例：

messages.json:

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

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

私信

翻译后的消息，以可包含占位符的字符串形式呈现。使用 $_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 $$)"


Although placeholders such as $USER$ are the preferred way of referring to substitution strings
(strings specified using the substitutions parameter of i18n.getMessage) you can also refer
to substitution strings directly within the message. For example, the following message refers to
the first three substitution strings passed into getMessage():



messages.json:


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



Despite that example, we recommend that you stick to using placeholders instead of $_n_ strings
within your messages. Think of placeholders as good variable names. A week after you write your
code, you'll probably forget what $1 refers to, but you'll know what your placeholders refer to.
For more information on placeholders and substitution strings, see the placeholders section.



description



Optional. A description of the message, intended to give context or details to help the translator
make the best possible translation.



Here are three examples of descriptions, taken from the Example section:



messages.json:


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



placeholders



Optional. Defines one or more substrings to be used within the message. Here are two reasons you
might want to use a placeholder:



    

  • To define the text for a part of your message that shouldn't be translated. Examples: HTML code,
trademarked names, formatting specifiers.
    • 

  • To refer to a substitution string passed into getMessage(). Example: $1.
    • 




Each placeholder has a name, a "content" item, and an optional "example" item. A placeholder's name
is case-insensitive and can contain the same characters as a message name.



The "content" item's value is a string that can refer to substitution strings, which are specified
using the i18n.getMessage method's substitutions parameter. The value of a "content" item is
typically something like "Example.com" or "$1". If you refer to a substitution string that doesn't
exist, you get an empty string. The following table shows how $_n_ strings correspond to strings
specified by the substitutions parameter.



substitutions parameterValue of $1Value of $2Value of $3
userNamevalue of userName""""
["Cira", "Kathy"]"Cira""Kathy"""



The "example" item (optional, but highly recommended) helps translators by showing how the content
appears to the end user. For example, a placeholder for a dollar amount should have an example like
"$23.45".



The following snippet, taken from the Example section, shows a "placeholders" item that
contains two placeholders named "our_site" and "user". The "our_site" placeholder has no "example"
item because its value is obvious from the "content" field.



messages.json:


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