Formats des messages de localisation

Chaque extension internationalisée comporte au moins un fichier nommé messages.json qui fournit des chaînes spécifiques aux paramètres régionaux. Cette page décrit le format des fichiers messages.json. Pour savoir comment internationaliser et localiser, consultez la page Internationalisation.

Récapitulatif des champs

Le code suivant montre les champs acceptés pour messages.json. Seuls les champs name et "message" sont obligatoires.

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

Exemple

Voici un fichier messages.json qui définit trois messages nommés "prompt_for_name", "hello" et "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"
      }
    }
  }
}

Détails du champ

Cette section décrit chaque champ pouvant figurer dans un fichier messages.json. Pour en savoir plus sur l'utilisation du fichier de messages (par exemple, ce qui se passe lorsqu'un paramètre régional ne définit pas tous les messages), consultez Internationalisation.

nom

En fait, il n'existe pas de champ "name". Le nom de ce champ est le nom du message, le même nom que vous voyez dans __MSG__name___ ou getMessage("_name_").

Le nom est une clé non sensible à la casse qui vous permet de récupérer le texte du message localisé. Le nom peut inclure les caractères suivants :

  • A-Z
  • a-z
  • 0-9
  • _ (trait de soulignement)
  • @

Voici trois exemples de noms tirés de la section Exemple :

messages.json:

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

Pour obtenir d'autres exemples d'utilisation des noms, consultez la page Internationalisation.

message

Message traduit, sous la forme d'une chaîne pouvant contenir des espaces réservés. Utilisez $_placeholder_name_$ (sans tenir compte de la casse) pour faire référence à un espace réservé spécifique. Par exemple, vous pouvez faire référence à un espace réservé nommé "our_site" en tant que $our_site$, $OUR_SITE$ ou $oUR_sITe$.

Voici trois exemples de messages tirés de la section Exemple :

messages.json:

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

Pour insérer un signe dollar ($) dans la chaîne, utilisez $$. 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"
  }
}