Cada extensión internacionalizada tiene al menos un archivo llamado messages.json que proporciona strings 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 admitidos para 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.
name
No hay ningún campo llamado "name". El nombre de este campo es el nombre del mensaje (el mismo nombre que se ve en __MSG__name___ o getMessage("_name_")).
El nombre es una clave que no distingue mayúsculas de minúsculas y te permite recuperar el texto localizado del mensaje. El nombre puede incluir los siguientes caracteres:
- A-Z
- a-z
- 0-9
- _ (guion bajo)
- @
Aquí hay tres ejemplos de nombres, tomados de la sección Ejemplos:
messages.json:
"prompt_for_name": {
...
},
"hello": {
...
},
"bye": {
...
}
Para ver más ejemplos del uso de nombres, consulta la página Internacionalización.
mensaje
Es el mensaje traducido, en forma de string que puede contener placeholders. Usa $_placeholder_name_$ (no distingue mayúsculas de 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$.
A continuación, se incluyen 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 colocar un signo de dólar ($) en la string, usa $$. For example, use the following code to specify
the message Amount (in $):
messages.json:
"message": "Amount (in $$)"Aunque los marcadores de posición, como
$USER$, son la forma preferida de hacer referencia a strings de sustitución (strings especificadas con el parámetro substitutions de i18n.getMessage), también puedes hacer referencia a strings de sustitución directamente dentro del mensaje. Por ejemplo, el siguiente mensaje hace referencia a las primeras tres strings de sustitución que se pasan agetMessage():messages.json:
"message": "Params: $1, $2, $3"A pesar de ese ejemplo, te recomendamos que no uses marcadores de posición en lugar de cadenas
$_n_en tus mensajes. Piensa en los marcadores de posición como buenos nombres de variables. Una semana después de escribir el código, es probable que olvides a qué hace referencia$1, pero sabrás a qué se refieren tus marcadores de posición. Para obtener más información sobre los marcadores de posición y las strings de sustitución, consulta la sección placeholders.descripción
Opcional. Es una descripción del mensaje, que brinda contexto o detalles para ayudar al traductor a realizar la mejor traducción posible.
Aquí hay tres ejemplos de descripciones, tomados de la sección Ejemplo:
messages.json:
"description": "Ask for the user's name" ... "description": "Greet the user" ... "description": "Say goodbye to the user"placeholders
Opcional. Define una o más substrings para usar en el mensaje. Estas son dos razones por las que te recomendamos usar un marcador de posición:
- Para definir el texto de una parte del mensaje que no se debe traducir. Ejemplos: Código HTML, nombres de marcas comerciales, especificadores de formato.
- Para hacer referencia a una string de sustitución que se pasa a
getMessage(). Ejemplo:$1.
Cada marcador de posición tiene un nombre, un elemento de "contenido" y un elemento de "ejemplo" opcional. El nombre de un marcador de posición no distingue mayúsculas de minúsculas y puede contener los mismos caracteres que el nombre de un mensaje.
El valor del elemento “contenido” es una string que puede hacer referencia a strings de sustitución, las cuales se especifican mediante el parámetro substitutions del método i18n.getMessage. El valor de un elemento de "contenido" suele ser similar a "Example.com" o "$1". Si haces referencia a una string de sustitución que no existe, obtendrás una string vacía. En la siguiente tabla, se muestra cómo las strings $_n_ se corresponden con las que especifica el parámetro substitutions.
| Parámetro substitutions | Valor de USD 1 | Valor de USD 2 | Valor de USD 3 |
|---|---|---|---|
userName | valor de userName | "" | "" |
["Cira", "Kathy"] | "Cira" | "Kathy" | "" |
El elemento "ejemplo" (opcional, pero muy recomendado) ayuda a los traductores, ya que les muestra cómo se muestra el contenido a los usuarios finales. Por ejemplo, un marcador de posición para un importe en dólares debería tener un ejemplo como "$23.45".
En el siguiente fragmento, tomado de la sección Ejemplo, se muestra un elemento de "marcadores de posición" que contiene dos marcadores de posición llamados "our_site" y "usuario". El marcador de posición "our_site" no tiene un elemento "example" porque su valor es obvio en el campo "content".
messages.json:
"placeholders": {
"our_site": {
"content": "Example.com",
},
"user": {
"content": "$1",
"example": "Cira"
}
}