Tout comme vous pouvez utiliser des groupes de ressources pour les messages dans les composants intégrés, les intentions de réponse, etc., vous pouvez également utiliser des groupes de ressources pour vos composants personnalisés. Pour ce faire :

1. Définissez des entrées de groupe de ressources dans la brique pour votre message. Reportez-vous à Création de clés de groupe de ressource.
2. A l'aide de la méthode context.translate() du kit SDK Bots Node, référencez les clés de groupe de ressources à partir du code de composant personnalisé.

   context.translate() prend un nom de clé de groupe de ressources spécifié (et tous les paramètres spécifiés dans l'entrée de groupe de ressources) et génère le modèle FreeMarker approprié requis pour charger la chaîne de langue du groupe de ressources nommé lorsque la conversation est renvoyée à l'utilisateur via la méthode context.reply().

3. Utilisez la méthode d'aide context.reply pour imprimer la réponse traduite. Par exemple :

   context.reply(translate('date.message', dateToday, dayOfWeek ));

4. Documentez toutes les clés de groupe de ressources référencées par le composant personnalisé ainsi que les chaînes par défaut attendues. (Le composant personnalisé faisant directement référence à la clé de groupe de ressources dans la brique, il doit y avoir un degré élevé de coordination entre le développeur du composant personnalisé et ceux qui créent la brique pour s'assurer que les clés référencées sont valides dans la brique).

Dans cet exemple, date.message est une clé de groupe de ressources, dateToday et dayOfWeek sont des variables et une expression FreeMarker telle que la suivante est renvoyée :

${rb('date.message', 'Monday', 'July 12, 2021')}

Vous pouvez utiliser un composant système pour assembler des messages à l'aide d'entrées de groupe de ressources et de données renvoyées par un composant personnalisé. Vous définissez les chaînes de message de base dans les entrées de groupe de ressources. Les entrées de groupe peuvent inclure des paramètres pour les données (telles que les nombres et les dates) qui sont générées à partir du composant personnalisé. Etant donné que les chaînes de message de base sont définies dans le flux de dialogue, cette approche garantit que les composants personnalisés ne dépendent pas d'un code d'implémentation spécifique et restent réutilisables.

Voici la procédure générale :

1. Pour le composant personnalisé, incluez un paramètre d'entrée obligatoire pour le nom de la variable de contexte dans lequel stocker les données renvoyées.
2. Etant donné que le développeur de composants personnalisés et le développeur de flux de dialogue peuvent ne pas être la même personne ou même de la même équipe, documentez soigneusement les données renvoyées par le composant personnalisé dans cette variable et mettez les informations à la disposition des consommateurs de composants personnalisés afin qu'ils comprennent comment présenter les données renvoyées à l'utilisateur dans un message.
3. Dans le flux de dialogue, créez une variable pour stocker les données renvoyées du composant personnalisé et transmettez son nom au paramètre d'entrée requis.
4. Définissez des entrées de groupe de ressources dans la brique pour votre message. Reportez-vous à Création de clés de groupe de ressource.
5. Dans le flux de dialogue, référencez l'entrée du groupe de ressources et renseignez les paramètres requis.

The following sample from a skill developed in YAML dialog mode references a custom component in the initializeReceipt state and passes the name of the variable (receipt) that holds the component response and purchaseId as input parameters. L'état printProduct intègre ensuite la valeur receipt en tant que paramètre dans une référence à l'entrée de groupe de ressources nommée receiptMessage.

  initializeReceipt:
    component: "sample.receipt.dataresponse"
    properties:
      dataVariable: "receipt"
      purchaseId: "${purchaseId.value}"
 ...
  printProduct:
    component: "System.CommonResponse"
    properties:
      keepTurn: true
      metadata:
        responseItems:        
        - type: "text" 
          text: "${rb('receiptMessage','${receipt.value}')}"

Le code personnalisé permettant d'accéder à ces paramètres d'entrée peut ressembler au code suivant :

module.exports = {
  metadata: () => ({
    name: 'myComponent',   
    properties: {
       dataVariable: { required: true, type: 'string' },    
       purchaseId: { required: true, type: 'string' },
    },
...
    // Retrieve the value of the 'dataVariable' component property.
    const { dataVariable } = context.properties();
    if (!dataVariable) {
      context.transition();
      done(new Error('The state is missing the dataVariable property.'));
    }
...
    // Retrieve the value of the 'purchaseId' component property.
    const { purchaseId } = context.properties();
    if (!purchaseId) {
      context.transition();
      done(new Error('The state is missing the purchaseId property.'));
    }
...
    context.setVariable(dataVariable, data);      
    context.transition();
    done();
  }
}

Si vous ne disposez pas d'un moyen de savoir quel sera le texte de réponse du composant (par exemple, s'il est interrogé à partir d'un back-end distant), vous pouvez utiliser le service de traduction de la brique pour traduire les réponses. Pour ce faire, procédez comme suit :

1. Assurez-vous que la sortie du composant est envoyée au service de traduction en définissant la propriété translate sur le composant et en la définissant sur true.
2. Dans le composant personnalisé, utilisez la méthode d'aide context.reply pour renvoyer la réponse.

Cette approche ne fonctionne qu'avec les compétences configurées en mode langue du service de traduction.

Les composants personnalisés interrogeant les services back-end peuvent renvoyer des données dans un format complexe, comme un objet ou un tableau d'objets. Si vous utilisez un service de traduction, ces objets de données ne peuvent pas être envoyés tels quels au service de traduction. Au lieu de cela, vous devez former un message qui référence tous les attributs nécessaires de l'objet de données individuellement.

1. Pour le composant personnalisé, incluez un paramètre d'entrée obligatoire pour le nom de la variable de flux de dialogue dans laquelle stocker les données renvoyées.
2. Etant donné que le développeur de composants personnalisés et le développeur de flux de dialogue peuvent ne pas être la même personne ou même de la même équipe, documentez soigneusement les données renvoyées par le composant personnalisé dans cette variable et mettez les informations à la disposition des consommateurs de composants personnalisés afin qu'ils comprennent comment présenter les données renvoyées à l'utilisateur dans un message.
3. Dans le flux de dialogue, créez une variable pour stocker les données renvoyées du composant personnalisé et transmettez son nom au paramètre d'entrée requis.
4. A l'aide des informations de la variable, assemblez la réponse dans un composant système, tel que Common Response.
5. Assurez-vous que la brique est configurée pour la traduction automatique.
   • Pour les briques développées en mode de dialogue visuel, définissez la propriété Translate Bot Response Message sur true sur la page Paramètres de la brique.
   • Pour les briques développées en mode de dialogue YAML, vous pouvez les gérer globalement dans la brique en définissant la variable de contexte autoTranslate. Par exemple :

       setAutoTranslate:
         component: "System.SetVariable"   
         properties:
           variable: "autoTranslate"     
           value:
            input: true
            output: true

responseItems:        
- type: "text" 
  text: "The product in your cart is a ${dialogVar.value.type}. It is
   ${dialogVar.value.product} from ${dialogVar.value.origin}"

Le code personnalisé permettant d'accéder à ce paramètre d'entrée peut ressembler au code suivant :

module.exports = {
  metadata: () => ({
    name: 'myComponent',   
    properties: {
       dialogVar: { required: true, type: 'string' },    
    },
...
    // Retrieve the value of the 'dialogVar' component property.
    const { dialogVar } = context.properties();
    if (!dialogVar) {
      context.transition();
      done(new Error('The state is missing the dialogVar property.'));
    }
...
    context.setVariable(dialogVar, data);    
    context.transition();
    done();
  }
}

Si le composant personnalisé a besoin de la langue de l'utilisateur pour effectuer des opérations telles que fournir des formats de date corrects, vous pouvez le fournir au composant de l'une des manières suivantes :

• Accédez aux variables profile.locale et profile.languageTag à partir du code de composant personnalisé, comme indiqué dans l'exemple suivant :

  //detect user locale. If not set, define a default
  const locale = context.getVariable('profile.locale') ?
                 context.getVariable('profile.locale') : 'en-AU';
  //Make sure locale is returned with hyphen, not underscore. JavaScript requires a hyphen.
  const jsLocale = locale.replace('_','-'); 
  //when profile languageTag is set, use it. If not, use profile.locale
  const languageTag = context.getVariable('profile.languageTag')?
                      context.getVariable('profile.languageTag') : jslocale;

• Transmettez les valeurs de profile.locale et/ou profile.languageTag en tant que paramètres d'entrée au composant.