Formats des messages de localisation

Chaque extension internationalisée comporte au moins un fichier nommé messages.json, qui fournit en fonction des 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 indique les champs compatibles avec messages.json. Uniquement le nom 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 apparaître dans un fichier messages.json. Pour en savoir plus sur l'utilisation de messages (par exemple, que se passe-t-il 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_").

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:

messages.json:

"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é "our_site" sous la forme $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 $$)"
.

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 à
trois premières chaînes de substitution transmises à getMessage():



messages.json:


"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 rédigé
vous oublierez probablement ce à quoi $1 fait référence, mais vous saurez à quoi correspondent les espaces réservés.
Pour en savoir plus sur les espaces réservés et les chaînes de substitution, consultez la section 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:



messages.json:


"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 dans 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.



Le terme "contenu" La valeur de l'élément est une chaîne pouvant faire référence à des chaînes de substitution, qui sont spécifiées
à l'aide du paramètre de 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
vous obtenez une chaîne vide. Le tableau suivant montre la correspondance entre les chaînes $_n_ et les chaînes.
spécifié par le paramètre substitutions.



Paramètre substitutionsValeur de 1 $Valeur de 2 $Valeur de 3 $
userNamevaleur 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 le terme "placeholders" élément qui
contient deux espaces réservés nommés "notre_site" et "user". La page "notre_site" l'espace réservé ne comporte pas d'"exemple"
car sa valeur est évidente dans le "contenu" .



messages.json :


"placeholders": {
  "our_site": {
    "content": "Example.com",
  },
  "user": {
    "content": "$1",
    "example": "Cira"
  }
}