Chaque extension ou application internationalisée comporte au moins un fichier nommé messages.json qui fournit des chaînes spécifiques à la langue. Cette page décrit le format des fichiers messages.json. Pour en savoir plus sur l'internationalisation et la localisation, consultez la page Internationalisation.
Récapitulatif des champs
Le code suivant indique les champs compatibles avec messages.json. Seuls les champs name (nom) et "message" (message) sont obligatoires.
{
"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":
{
"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 apparaître 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 la section Internationalisation.
nom
En fait, il n'existe pas de champ appelé "name". Le nom de ce champ est le nom du message, le même nom que celui 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 localisé du message. 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:
"prompt_for_name": {
...
},
"hello": {
...
},
"bye": {
...
}
Pour plus d'exemples d'utilisation de 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_$ (insensible à la casse) pour faire référence à un espace réservé particulier. Par exemple, vous pouvez faire référence à un espace réservé nommé "our_site" sous la forme $our_site$, $OUR_SITE$ ou $oUR_sITe$.
Voici trois exemples de messages, tirés de la section Exemple:
"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 $):
"message": "Amount (in $$)"Bien que les espaces réservés tels que
$USER$soient le moyen privilégié de faire référence aux chaînes de substitution (chaînes spécifiées à l'aide du paramètre substitutions de i18n.getMessage), vous pouvez également faire référence aux chaînes de substitution directement dans le message. Par exemple, le message suivant fait référence aux trois premières chaînes de substitution transmises àgetMessage():"message": "Params: $1, $2, $3"Malgré cet exemple, nous vous recommandons de vous en tenir à l'utilisation d'espaces réservés plutôt que de chaînes
$_n_dans vos messages. Considérez les espaces réservés comme de bons noms de variables. Une semaine après avoir rédigé votre code, vous oublierez probablement ce à quoi$1fait référence, mais vous saurez à quoi correspondent vos espaces réservés. Pour en savoir plus sur les espaces réservés et les chaînes de substitution, consultez la section relative aux espaces réservés.description
Facultatif. Description du message, destinée à fournir du contexte ou des détails afin d'aider le traducteur à générer la meilleure traduction possible.
Voici trois exemples de descriptions, tirés de la section Exemple:
"description": "Ask for the user's name" ... "description": "Greet the user" ... "description": "Say goodbye to the user"espaces réservés
Facultatif. Définit une ou plusieurs sous-chaînes à utiliser dans le message. Voici deux raisons pour lesquelles vous pouvez utiliser un espace réservé:
- Pour définir le texte d'une partie de votre message qui ne doit pas être traduit. Exemples: code HTML, noms de marques, spécificateurs de mise en forme.
- Pour faire référence à une chaîne de substitution transmise à
getMessage(). Exemple :$1.
Chaque espace réservé possède un nom, un élément "contenu" et un élément "exemple" facultatif. Le nom d'un espace réservé n'est pas sensible à la casse et peut contenir les mêmes caractères qu'un nom de message.
La valeur de l'élément"content" est une chaîne qui peut faire référence à des chaînes de substitution, qui sont spécifiées à l'aide du paramètre substitutions de la méthode i18n.getMessage. La valeur d'un élément "contenu" est généralement "Example.com" ou "1 $". Si vous faites référence à une chaîne de substitution qui n'existe pas, vous obtenez une chaîne vide. Le tableau suivant montre comment les chaînes $_n_ correspondent aux chaînes spécifiées par le paramètre substitutions.
| Paramètre substitutions | Valeur de 1 $ | Valeur de 2 € | Valeur de 3 $ |
|---|---|---|---|
userName | valeur de userName | "" | "" |
["Cira", "Kathy"] | "Cira" | "Kathy" | "" |
L'élément "exemple" (facultatif, mais fortement recommandé) aide les traducteurs en montrant comment le contenu s'affiche pour l'utilisateur final. Par exemple, un espace réservé pour un montant en dollars doit être accompagné d'un exemple comme "$23.45".
L'extrait suivant, issu de la section Example, montre un élément "placeholders" qui contient deux espaces réservés nommés "our_site" et "user" (utilisateur). L'espace réservé "our_site" ne comporte pas d'élément "exemple", car sa valeur est évidente dans le champ "content".
"placeholders": {
"our_site": {
"content": "Example.com",
},
"user": {
"content": "$1",
"example": "Cira"
}
}