Message : global

L’API Message Server vous permet de récupérer des messages localisés de la table Message [sys_ui_message] pour une entrée avec un code égal au paramètre code, une clé égale au paramètre message et une langue égale à la langue de la session (ou langue de secours).

L’API Message prend en charge l’internationalisation (i18n) en extrayant dynamiquement les messages en fonction de la langue de la session de l’utilisateur ou d’un paramètre de langue spécifié. Cette API offre trois fonctionnalités principales :

• Désambiguïsation : Utilise une clé composée de code et de message pour distinguer les chaînes identiques utilisées dans différents contextes (par exemple, « ouvrir » en tant que verbe par rapport à un nom).
• Paramètres nommés : permet l’interpolation dynamique de valeurs dans des modèles de message à l’aide d’espaces réservés nommés.
• Contrôle de la langue : getMessageLang vous permet de spécifier une langue cible, utile pour des scénarios tels que les fusions de messages ou les notifications multilingues 2 3.

L’API de message est fournie avec le système de base standard dans l’espace de noms sn_i18n et ne nécessite aucun module d’extension ou rôle spécial pour y accéder. Avant d’appeler des méthodes de cette classe, assurez-vous que des enregistrements de message [sys_ui_message] appropriés existent et qu’ils sont renseignés avec des champs de clé et de code correspondants.

Message.getMessage (code de chaîne, message de chaîne, arguments de carte)

Récupère un message localisé à partir de la table Message [sys_ui_message] tout en permettant la levée de l’ambiguïté et l’insertion de contenu dynamique.

L’API prend en charge les commentaires en ligne pour les traducteurs, ce qui améliore la clarté et réduit l’ambiguïté dans les contextes multilingues. Les commentaires ne sont pas utilisés dans le champ clé du message [sys_ui_message], mais la chaîne commentée peut être ajoutée au champ « commented_message ». Les valeurs du paramètre args sont interpolées dans les littéraux de modèle correspondants dans la chaîne.

Tableau 1. Paramètres

Nom	Type	Description
code	Chaîne	Requis. Une clé de désambiguïsation pour distinguer les messages avec un texte similaire mais des significations ou des contextes différents. Un nom de périmètre peut être utilisé si la chaîne est unique dans le scope. Si une désambiguïsation supplémentaire est nécessaire, elle peut être augmentée. Par exemple, « ouvert » peut signifier un état ou une action, et le paramètre de code permet de clarifier lequel. Si nous avons besoin de 2 messages avec la même chaîne mais une casse différente, le script serait le suivant : sn_i18n.Message.getMessage("scopeName-open-capitalized", "Open"); sn_i18n.Message.getMessage("scopeName-open", "open");
message	Chaîne	Facultatif. La chaîne de message par défaut à utiliser si aucune version localisée n’est trouvée. Correspond au champ clé de la table Message [sys_ui_message].
args	JSON	Facultatif. Carte de paramètres nommés utilisés pour insérer dynamiquement des valeurs dans le message. Les clés correspondent aux paramètres nommés dans le message. Les valeurs peuvent être des chaînes de caractères littéraux ou des variables/constantes dans le champ d’application. Par exemple, si votre message est « Hello, ${John} ! », vous pouvez passer {name : « John"} pour rendre « Hello, John ! ».

Tableau 2. Renvoie

Type

Description

Chaîne

Renvoie une valeur de la table Message [sys_ui_message] où : Les 255 premiers caractères du paramètre de message correspondent au champ clé. Les 255 premiers caractères du paramètre de code correspondent au champ de code. Le champ de langue (ou la langue de la session si aucun champ de langue n’est spécifié) correspond au champ de langue. Si aucune correspondance n’est trouvée, toutes les langues de secours sont vérifiées pour trouver une correspondance (voir Set a fallback language). Si aucune correspondance n’est toujours trouvée, la valeur du message (2e paramètre) est renvoyée et est dépouillée des commentaires. Les paramètres nommés sont remplacés par les valeurs spécifiées dans la carte transmise dans le paramètre args.

L’exemple suivant appelle la méthode getMessage() pour lever l’ambiguïté d’un enregistrement existant dans la table Message [sys_ui_message] en français, qui est la langue de la session utilisateur. Le bloc de code suivant contient le contenu du message.

<?xml version="1.0" encoding="UTF-8"?>
<xml>
	<sys_ui_message>
		<code>exampleCode</code>
		<key>User {username} has been added as {role}</key>
		<language>fr</language>
		<message>L'utilisateur {username} a été ajouté en tant que {role}</message>
	</sys_ui_message>
</xml>

L’exemple exécute le script d’API avec une langue de session en français :

//defines a user object using the name and role properties
var user = {
name: "Fred Luddy",
role: "maint"
}

//retrieves a localized message where code: "exampleCode" is the disambiguation key, message: User {username} has been added as {role}" is the default message template, and args: username: user.name, role: user.role } is a map of named parameters that will replace {username} and {role} in the message.
gs.info(sn_i18n.Message.getMessage("exampleCode","User {username} has been added as {role}",{username: user.name, role: user.role}));

La sortie contient le message en français :

//English: User Fred Luddy has been added as maint
L'utilisateur Fred Luddy a été ajouté en tant que maint

Utilisation de base sans paramètres nommés

// Retrieves a localized message using only code and default message
var message = sn_i18n.Message.getMessage("status.open", "Open");
gs.info(message); // Output depends on user's session language

Cet exemple utilise code (« satus.open ») pour lever l’ambiguïté du message, et message ("Open") comme solution de secours si aucune traduction n’est trouvée.

Utilisation de base avec paramètres nommés

/ Retrieves a localized message with named parameters
var message = sn_i18n.Message.getMessage(
  "greeting.personal",
  "Hello, ${name}! You have ${count} new messages.",
  { name: "John", count: 5 }
);
gs.info(message); // Output: "Hello, John! You have 5 new messages." (localized if available)

Cet exemple utilise code (« greeting.personal ») distingue cette salutation des autres, et message est un modèle avec des espaces réservés. args ({name : « John », count : 5}) remplit les espaces réservés.

Message.getMessageLang(Code de chaîne, Message de chaîne, Mapper les args, Langage de chaîne)

Récupère un message localisé dans le message [sys_ui_message] dans une langue donnée, quelle que soit la langue de la session de l’utilisateur actuel.

L’API prend en charge les commentaires en ligne pour les traducteurs, ce qui améliore la clarté et réduit l’ambiguïté dans les contextes multilingues. Les commentaires ne sont pas utilisés dans le champ clé du message [sys_ui_message], mais la chaîne commentée peut être ajoutée au champ « commented_message ». Les valeurs du paramètre args sont interpolées dans les littéraux de modèle correspondants dans la chaîne.

getMessageLang() est utile pour :

• Remplacement de la langue de la session : utile pour envoyer des notifications, des e-mails ou des rapports dans une langue spécifique.
• Prise en charge multilingue : idéale pour les applications qui desservent des utilisateurs dans différentes régions.
• Test des traductions : aide les développeurs à prévisualiser la façon dont les messages apparaissent dans d’autres langues sans changer de paramètres utilisateur.

Tableau 3. Paramètres

Nom	Type	Description
code	Chaîne	Requis. Une clé de désambiguïsation pour distinguer les messages avec un texte similaire mais des significations ou des contextes différents. Un nom de périmètre peut être utilisé si la chaîne est unique dans le scope. Si une désambiguïsation supplémentaire est nécessaire, elle peut être augmentée. Par exemple, « ouvert » peut signifier un état ou une action, et le paramètre de code permet de clarifier lequel. Si nous avons besoin de 2 messages avec la même chaîne mais une casse différente, le script serait le suivant : sn_i18n.Message.getMessage("scopeName-open-capitalized", "Open"); sn_i18n.Message.getMessage("scopeName-open", "open");
message	Chaîne	Facultatif. La chaîne de message par défaut à utiliser si aucune version localisée n’est trouvée. Correspond au champ clé de la table Message [sys_ui_message].
args	JSON	Facultatif. Carte de paramètres nommés utilisés pour insérer dynamiquement des valeurs dans le message. Les clés correspondent aux paramètres nommés dans le message. Les valeurs peuvent être des chaînes de caractères littéraux ou des variables/constantes dans le champ d’application. Par exemple, si votre message est « Hello, ${John} ! », vous pouvez passer {name : « John"} pour rendre « Hello, John ! ».
language	Chaîne	Facultatif. Langue dans laquelle renvoyer le message. Format : code de langue BCP-47 Par défaut : langue de la session

Tableau 4. Renvoie

Type

Description

Chaîne

Renvoie une valeur de la table Message [sys_ui_message] où : Les 255 premiers caractères du paramètre de message correspondent au champ clé. Les 255 premiers caractères du paramètre de code correspondent au champ de code. Le champ de langue (ou la langue de la session si aucun champ de langue n’est spécifié) correspond au champ de langue. Si aucune correspondance n’est trouvée, toutes les langues de secours sont vérifiées pour trouver une correspondance (voir Set a fallback language). Si aucune correspondance n’est toujours trouvée, la valeur du message (2e paramètre) est renvoyée et est dépouillée des commentaires. Les paramètres nommés sont remplacés par les valeurs spécifiées dans la carte transmise dans le paramètre args.

L’exemple suivant appelle la méthode getMessageLang() pour traduire un enregistrement existant dans la table Message [sys_ui_message] en japonais. Le bloc de code suivant contient le contenu du message.

<?xml version="1.0" encoding="UTF-8"?>
<xml>
	<sys_ui_message>
		<code>exampleCode</code>
		<key>User {username} has been added as {role}</key>
		<language>ja</language>
		<message> {username} が {role} として追加されました。</message>
	</sys_ui_message>
</xml>

L’exemple exécute le script d’API avec une langue de session autre que le japonais :

var user = {
    name: "Fred Luddy",
    role: "maint"
}
gs.info(sn_i18n.Message.getMessageLang("exampleCode","User {username} has been added as {role}",{username: user.name, role: user.role}, "ja"));

La sortie contient le message en japonais :

Fred Luddy が maint として追加されました

Les exemples suivants utilisent des paramètres nommés (${username}, ${role}) pour le contenu dynamique, spécifient une langue cible à l’aide de codes de langue ISO (« fr », « ja », « es ») et garantissent le retour au message par défaut si aucune traduction n’est trouvée.

Notification en français :

var user = {
  name: "Fred Luddy",
  role: "maint"
};

var message = sn_i18n.Message.getMessageLang(
  "user.added",
  "User ${username} has been added as ${role}",
  { username: user.name, role: user.role },
  "fr" // French
);

gs.info(message); // Output: "L'utilisateur Fred Luddy a été ajouté en tant que maint" (if translation exists)

Notification en japonais :

var user = {
  name: "Hanako Yamada",
  role: "admin"
};

var message = sn_i18n.Message.getMessageLang(
  "user.added",
  "User ${username} has been added as ${role}",
  { username: user.name, role: user.role },
  "ja" // Japanese
);

gs.info(message); // Output: "ユーザー Hanako Yamada が admin として追加されました" (if translation exists)

Notification en espagnol :

var user = {
  name: "Carlos Ruiz",
  role: "editor"
};

var message = sn_i18n.Message.getMessageLang(
  "user.added",
  "User ${username} has been added as ${role}",
  { username: user.name, role: user.role },
  "es" // Spanish
);

gs.info(message); // Output: "El usuario Carlos Ruiz ha sido añadido como editor" (if translation exists)