Formats des messages de localisation

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 plus d'informations sur comment internationaliser et localiser, consultez la page Internationalisation.

Récapitulatif des champs

Le code suivant indique les champs compatibles avec messages.json. Uniquement le nom et "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'y a 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_").

Il s'agit d'une clé non sensible à la casse qui vous permet de récupérer le texte du message localisé. Le nom peut comprennent 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_$ (non sensible à 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é « notre_site » comme $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é pour 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 au lieu 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 écrit votre code, vous oublierez probablement à quoi $1 fait référence, mais vous saurez à quoi font référence 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 pour aider le traducteur à effectuer 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,
les noms de marque commerciale, les spécificateurs de mise en forme.
Pour faire référence à une chaîne de substitution transmise à getMessage(). Exemple : $1.


Chaque espace réservé a un nom, un "contenu" et un "exemple" facultatif élément. Nom d'un espace réservé
ne sont pas sensibles à la casse et peuvent contenir les mêmes caractères que le nom d'un 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 "contenu" l'élément est
généralement quelque chose comme 
« 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'exemple item (facultatif, mais fortement recommandé) aide les traducteurs en leur montrant comment le contenu
apparaît à l'utilisateur final. Par exemple, un espace réservé pour un montant en dollars doit avoir un exemple comme
"$23.45"

L'extrait de code suivant, extrait de la section Exemple, montre un élément "espaces réservés" contenant deux espaces réservés nommés "our_site" et "user". La page "notre_site" l'espace réservé ne comporte pas d'"exemple"
car sa valeur est évidente dans le "contenu" .
"placeholders": {
  "our_site": {
    "content": "Example.com",
  },
  "user": {
    "content": "$1",
    "example": "Cira"
  }
}