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

1. Définissez les entrées d'ensemble de ressources dans la compétence pour votre message. Voir Créer des clés d'ensemble de ressources.
2. À l'aide de la méthode context.translate() de la trousse SDK de développement de robots, référencez les clés d'ensemble de ressources à partir du code de composant personnalisé.

   context.translate() prend un nom de clé d'ensemble de ressources spécifié (et tous les paramètres spécifiés dans l'entrée d'ensemble de ressources) et génère le modèle FreeMarker approprié requis pour charger la chaîne de langue de l'ensemble de ressources nommé lorsque la conversation est renvoyée à l'utilisateur au moyen de 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 d'ensemble de ressources référencées par le composant personnalisé ainsi que les chaînes par défaut attendues. (Comme le composant personnalisé référence directement la clé d'ensemble de ressources dans la compétence, il doit y avoir un degré élevé de coordination entre le développeur du composant personnalisé et ceux qui créent la compétence pour s'assurer que les clés référencées sont valides dans la compétence).

Dans cet exemple, date.message est une clé d'ensemble de ressources, dateToday et dayOfWeek sont des variables, et une expression FreeMarker comme suit est retournée :

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

Vous pouvez utiliser un composant système pour assembler des messages à l'aide d'entrées d'ensembles de ressources et de données qui ont été retournées à partir d'un composant personnalisé. Vous définissez les chaînes de message de base dans les entrées d'ensemble de ressources. Les entrées d'ensemble peuvent inclure des paramètres pour les données (comme les nombres et les dates) qui sont sorties du composant personnalisé. Étant 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 de mise en oeuvre spécifique et restent réutilisables.

Voici les étapes générales :

1. Pour le composant personnalisé, incluez un paramètre d'entrée obligatoire pour le nom de la variable de contexte dans laquelle stocker les données retournées.
2. Étant 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 au sein de la même équipe, documentez soigneusement les données retournées par le composant personnalisé dans cette variable et mettez les informations à la disposition de tous les consommateurs de composants personnalisés afin qu'ils comprennent comment présenter les données retournées à l'utilisateur dans un message.
3. Dans le flux de dialogue, créez une variable pour stocker les données retournées du composant personnalisé et transmettez son nom dans le paramètre d'entrée requis.
4. Définissez les entrées d'ensemble de ressources dans la compétence pour votre message. Voir Créer des clés d'ensemble de ressources.
5. Dans le flux de dialogue, référencez l'entrée d'ensemble de ressources et entrez les paramètres requis.

L'exemple suivant d'une compétence développée en mode de dialogue YAML référence un composant personnalisé dans l'état initializeReceipt et transmet comme paramètres d'entrée le nom de la variable (receipt) qui contient la réponse du composant et purchaseId. L'état printProduct intègre ensuite la valeur receipt en tant que paramètre dans une référence à l'entrée d'ensemble 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 n'avez aucun moyen de savoir quel sera le texte de réponse du composant (par exemple, s'il est interrogé à partir d'un système dorsal distant), vous pouvez utiliser le service de traduction de la compétence pour traduire les réponses. Pour ce faire :

1. Assurez-vous que la sortie du composant est configurée pour être envoyée au service de traduction en définissant la propriété translate sur le composant et en la réglant à true.
2. Dans le composant personnalisé, utilisez la méthode d'aide context.reply pour retourner 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 qui interrogent les services dorsaux peuvent retourner 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 au service de traduction tel quel. Au lieu de cela, vous devez former un message qui référence 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 retournées.
2. Étant 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 au sein de la même équipe, documentez soigneusement les données retournées par le composant personnalisé dans cette variable et mettez les informations à la disposition de tous les consommateurs de composants personnalisés afin qu'ils comprennent comment présenter les données retournées à l'utilisateur dans un message.
3. Dans le flux de dialogue, créez une variable pour stocker les données retournées du composant personnalisé et transmettez son nom dans le paramètre d'entrée requis.
4. A l'aide des informations de la variable, assemblez la réponse dans un composant système, par exemple Common Response.
5. Assurez-vous que la compétence est configurée pour la traduction automatique.
   • Pour les compétences développées en mode de dialogue visuel, réglez la propriété Translate Bot Response Message (Message de réponse du robot de traduction) dans la page Settings (Paramètres) de la compétence à true.
   • Pour les compétences développées en mode de dialogue YAML, vous pouvez les gérer globalement dans la compétence 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 fournir des formats de date corrects, vous pouvez le fournir au composant de l'une des façons suivantes :

• Accédez aux variables profile.locale et profile.languageTag à partir du code de composant personnalisé, comme illustré 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.