ローカライズ メッセージの形式

国際化された拡張機能またはアプリには、少なくとも 1 つの 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."
      },
      ...
    }
  },
  ...
}

例

以下に、「prompt_for_name」、「hello」、「bye」という 3 つのメッセージを定義する 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_") に表示される name と同じです。

名前は、ローカライズされたメッセージ テキストを取得できる大文字と小文字が区別されないキーです。名前には次の文字を含めることができます。

  • 名前順（昇順）
  • a-z
  • 0～9
  • _（アンダースコア）
  • @
注: 「@@」で始まる名前は定義しないでください。これらの名前は事前定義されたメッセージ用に予約されています。

例セクションから抜粋した名前の例を 3 つ示します。

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

名前の使用例については、国際化のページをご覧ください。

メッセージ

翻訳されたメッセージ。プレースホルダを含むことができる文字列の形式。$_placeholder_name_$（大文字と小文字を区別しない）を使用して、特定のプレースホルダを参照します。たとえば、「our_site」という名前のプレースホルダは、$our_site$、$OUR_SITE$、$oUR_sITe$ として参照できます。

例セクションから抜粋したメッセージの例を 3 つ示します。

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

 を使用します。
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():


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


"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.


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