Formatos de mensajes de localización

Cada extensión internacionalizada tiene al menos un archivo llamado messages.json que proporciona cadenas específicas de la configuración regional. En esta página, se describe el formato de los archivos messages.json. Para obtener información sobre cómo internacionalizar y localizar, consulta la página Internacionalización.

Resumen del campo

En el siguiente código, se muestran los campos compatibles con messages.json. Solo se requieren los campos "name" y "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."
      },
      ...
    }
  },
  ...
}

Ejemplo

Este es un archivo messages.json que define tres mensajes llamados "prompt_for_name", "hello" y "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"
      }
    }
  }
}

Detalles del campo

En esta sección, se describe cada campo que puede aparecer en un archivo messages.json. Para obtener detalles sobre cómo se usa el archivo de mensajes (por ejemplo, qué sucede cuando una configuración regional no define todos los mensajes), consulta Internacionalización.

nombre

En realidad, no hay ningún campo llamado "name". El nombre de este campo es el nombre del mensaje, el mismo nombre que ves en __MSG__name___ o getMessage("_name_").

El nombre es una clave que no distingue mayúsculas de minúsculas y que te permite recuperar el texto del mensaje localizado. El nombre puede incluir los siguientes caracteres:

  • A-Z
  • a-z
  • 0-9
  • _ (guion bajo)
  • @

Estos son tres ejemplos de nombres, tomados de la sección Ejemplo:

messages.json:

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

Para obtener más ejemplos sobre el uso de nombres, consulta la página Internacionalización.

mensaje

Es el mensaje traducido, en forma de una cadena que puede contener marcadores de posición. Usa $_placeholder_name_$ (sin distinción entre mayúsculas y minúsculas) para hacer referencia a un marcador de posición en particular. Por ejemplo, puedes hacer referencia a un marcador de posición llamado "our_site" como $our_site$, $OUR_SITE$ o $oUR_sITe$.

Estos son tres ejemplos de mensajes tomados de la sección Ejemplo:

messages.json:

"message": "What's your name?"
...
"message": "Hello, $USER$"
...
"message": "Goodbye, $USER$. Come back to $OUR_SITE$ soon!"

Para incluir un signo de dólar ($) en la cadena, usa $$. 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"
  }
}