Cada extensión o app 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 de campos
En el siguiente código, se muestran los campos admitidos para messages.json. Solo se requieren los campos “name” y “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."
},
...
}
},
...
}
Ejemplo
Este es un archivo messages.json que define tres mensajes llamados "prompt_for_name", "hello" y "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"
}
}
}
}
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 un campo llamado "name". El nombre de este campo es el nombre del mensaje (el mismo name 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:
"prompt_for_name": {
...
},
"hello": {
...
},
"bye": {
...
}
Para obtener más ejemplos de uso de nombres, consulta la página Internacionalización.
mensaje
Es el mensaje traducido, en el formato 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 "nuestro_sitio" como $our_site$, $OUR_SITE$ o $oUR_sITe$.
Estos son tres ejemplos de mensajes, tomados de la sección Ejemplo:
"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 cadena, usa $$. For example, use the following code to specify
the message Amount (in $):
"message": "Amount (in $$)".Aunque los marcadores de posición, como
$USER$, son la forma preferida de hacer referencia a las cadenas de sustitución (cadenas especificadas con el parámetro Proposals en i18n.getMessage), también puedes hacer referencia a las strings de sustitución directamente dentro del mensaje. Por ejemplo, el siguiente mensaje hace referencia a las tres primeras strings de sustitución que se pasan agetMessage():"message": "Params: $1, $2, $3"A pesar de ese ejemplo, te recomendamos que 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 marcadores de posición y strings de sustitución, consulta la sección de marcadores de posición.descripción
Opcional. Es una descripción del mensaje, destinada a proporcionar contexto o detalles para ayudar al traductor a realizar la mejor traducción posible.
Estos son tres ejemplos de descripciones, tomados de la sección Ejemplo:
"description": "Ask for the user's name" ... "description": "Greet the user" ... "description": "Say goodbye to the user"marcadores de posición
Opcional. Define una o más subcadenas que se usarán en el mensaje. Estos son dos motivos por los que podrías usar un marcador de posición:
- Para definir el texto de una parte del mensaje que no debe traducirse. Ejemplos: código HTML, nombres de marcas comerciales y especificadores de formato.
- Para hacer referencia a una string de sustitución pasada a
getMessage(). Ejemplo:$1.
Cada marcador de posición tiene un nombre, un elemento "content" y un elemento "example" opcional. El nombre de un marcador de posición no distingue mayúsculas de minúsculas y puede contener los mismos caracteres que un nombre de mensaje.
El valor del elemento “contenido” es una cadena que puede hacer referencia a cadenas de sustitución, que se especifican con el parámetro optionals del método i18n.getMessage. El valor de un elemento "content" suele ser algo como "Example.com" o "USD 1". Si te refieres a una string de sustitución que no existe, obtendrás una string vacía. En la siguiente tabla, se muestra cómo las cadenas $_n_ corresponden a las cadenas especificadas por 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 recomendable) ayuda a los traductores, ya que muestra cómo se muestra el contenido al usuario final. Por ejemplo, un marcador de posición para un importe en dólares debe tener un ejemplo como "$23.45".
En el siguiente fragmento, tomado de la sección Ejemplo, se muestra un elemento "marcadores de posición" que contiene dos marcadores de posición llamados "our_site" y "user". El marcador de posición "our_site" no tiene el elemento "example" porque su valor es obvio en el campo "content".
"placeholders": {
"our_site": {
"content": "Example.com",
},
"user": {
"content": "$1",
"example": "Cira"
}
}