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 en savoir plus sur l'internationalisation et la localisation, 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'une langue ne définit pas tous les messages), consultez la section Internationalisation.

name

En fait, il n'y a pas de champ appelé "name". Le nom de ce champ est le nom du message, c'est-à-dire 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 du message localisé. Ce nom peut inclure les caractères suivants:

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

Voici trois exemples de noms extraits de la section Exemple:

messages.json:

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

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

message

Message traduit, sous la forme d'une chaîne pouvant contenir des placeholders. Utilisez $_placeholder_name_$ (non sensible à 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" par $our_site$, $OUR_SITE$ ou $oUR_sITe$.

Voici trois exemples de messages extraits 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$ constituent la méthode privilégiée 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 dans 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 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 é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 plus d'informations sur les espaces réservés et les chaînes de substitution, consultez la section placeholders.



description



Facultatif. Description du message destinée à fournir du contexte ou des détails pour aider le traducteur à produire la meilleure traduction possible.



Voici trois exemples de descriptions tirées de la section Exemple:



messages.json:


"description": "Ask for the user's name"
...
"description": "Greet the user"
...
"description": "Say goodbye to the user"



placeholders



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é:



    

  • Permet de définir le texte de la partie de votre message qui ne doit pas être traduite. Exemples: code HTML, noms de marques, spécificateurs de mise en forme.
    • 

  • Faire référence à une chaîne de substitution transmise dans getMessage(). Exemple : $1.
    • 




Chaque espace réservé peut être associé à un nom, à un élément "content" et à un élément facultatif "example". 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, spécifiées à l'aide du paramètre de substitutions de la méthode i18n.getMessage. La valeur d'un élément "content" est généralement de type "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 de substitutions.



Paramètre substitutionsValeur de 1 $Valeur de 2 $Valeur de 3 $
userNamevaleur de userName""""
["Cira", "Kathy"]"Cira""Kathy"""



L'élément "example" (facultatif, mais vivement recommandé) aide les traducteurs en leur montrant comment le contenu s'affiche pour l'utilisateur final. Par exemple, un espace réservé pour un montant en dollars doit contenir un exemple tel que "$23.45".



L'extrait de code suivant, tiré de la section Example, montre un élément "placeholders" contenant deux espaces réservés nommés "our_site" et "user". L'espace réservé "our_site" ne contient pas d'élément "example", car sa valeur est évidente dans le champ "content".



messages.json:


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