Tout comme vous pouvez utiliser des ensembles de ressources pour les messages dans des composants intégrés, des 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 des 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 auxquelles le composant personnalisé fait référence, ainsi que les chaînes par défaut attendues. (Puisque 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 similaire à ce qui 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'ensemble de ressources et de données retournées par un composant personnalisé. Vous définissez les chaînes de message de base dans les entrées d'ensemble de ressources. Les entrées de l'ensemble peuvent inclure des paramètres pour les données (telles que les nombres et les dates) qui sont extraites du composant personnalisé. Comme 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 ne sont peut-être pas la même personne ou même dans la même équipe, documentez soigneusement les données retourné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 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 des 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 tous les paramètres requis.

L'exemple suivant d'une compétence développée en mode de boîte 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 serveur 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 de 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. Vous devez plutôt former un message qui référence individuellement tous les attributs nécessaires de l'objet de données.

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 ne sont peut-être pas la même personne ou même dans la même équipe, documentez soigneusement les données retourné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 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. À 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 (Traduire le message de réponse du robot) de 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.