Groupes de ressources pour les briques

Si votre brique est conçue pour gérer plusieurs langues et que vous voulez contrôler la formulation de ses réponses, utilisez des groupes de ressources. Vous pouvez fournir des groupes de ressources pour autant de langues et de dialectes que nécessaire.

Même si votre brique cible une seule langue, l'utilisation de regroupements de ressources présente des avantages, tels que le fait de placer l'ensemble de votre texte destiné à l'utilisateur au même endroit.

Plusieurs options sont disponibles pour paramétrer les entrées de groupe de ressources, ce qui vous permet d'intégrer des variables dans les chaînes. En outre, vous pouvez utiliser le formatage ICU dans les entrées de groupe afin de faciliter la formulation d'une réponse en fonction de la résolution de ses paramètres. Vous avez ainsi la possibilité, par exemple, d'ajuster la formulation en fonction de l'emploi du singulier ou du pluriel.

Types de clé de groupe de ressources

Les chaînes côté utilisateur d'une brique proviennent de plusieurs parties de la brique. Dans certains cas, une clé de groupe de ressources est automatiquement créée pour vous. Dans d'autres cas, aucune clé n'est générée, mais vous pouvez en définir une vous-même.

Voici les emplacements desquels les chaînes côté utilisateur proviennent et la manière de les gérer dans le groupe de ressources.

Champ Nom de la conversation pour les intentions.
Lorsque vous définissez des noms de conversation, des clés de groupe de ressources sont créées automatiquement et remplies avec la valeur que vous avez définie pour la langue par défaut. Pour accéder aux clés de groupe associées aux noms de conversation, cliquez sur et sélectionnez l'onglet Intentions.
Champ Réponse pour les intentions (intentions de réponse).
Lorsque vous définissez des réponses dans les intentions, des clés de groupe de ressources sont créées automatiquement et remplies avec le texte de réponse dans la langue par défaut. Pour accéder aux clés de groupe des réponses, cliquez sur et sélectionnez l'onglet Questions/réponses.
Paramètres de configuration de la brique (accessibles en cliquant sur et en sélectionnant l'onglet Configuration).
Pour ces paramètres, les clés de groupe de ressources sont générées avec des valeurs par défaut, et les valeurs de paramètre sont exprimées en tant que références aux clés de groupe de ressources. Pour modifier les valeurs de ces clés, cliquez sur et sélectionnez l'onglet Configuration.
Invites, libellés et messages par défaut intégrés aux composants de flux de dialogue standard.
Pour modifier la valeur par défaut de l'une de ces propriétés, cliquez sur dans le groupe de ressources et sélectionnez l'onglet Configuration.

Vous n'avez pas besoin d'ajouter la propriété au composant dans la définition de flux de dialogue pour référencer la valeur mise à jour dans le groupe de ressources.

Si vous voulez modifier la valeur de l'une de ces propriétés pour un composant dans un état particulier sans modifier la valeur par défaut, ajoutez la propriété au composant dans cet état.
Chaîne de flux de dialogue. Pour le texte que vous incorporez dans vos composants, vous pouvez définir vos propres clés de groupe de ressources, puis les référencer à partir de la définition de flux de dialogue.
Pour créer et modifier ces clés, cliquez sur et sélectionnez l'onglet Défini par l'utilisateur.
Invites et messages provenant de définitions d'entité. Pour ces chaînes, vous pouvez définir vos propres clés de groupe de ressources, puis référencer ces clés à partir des champs de ces propriétés dans la définition d'entité.
Afin de créer et de modifier des clés pour ces chaînes, cliquez sur et sélectionnez l'onglet Défini par l'utilisateur.

Remarque

Les groupes de ressources ne constituent pas le mécanisme de traduction des entités de liste de valeurs. Vous fournissez la traduction dans la définition d'entité personnalisée. Pour les briques utilisant des langues prises en charge de façon native, vous fournissez des valeurs pour ces langues. Pour les briques basées sur un service de traduction, vous fournissez les valeurs traduites comme synonymes des valeurs dans la langue par défaut.

Création de clés de groupe de ressources

Les clés de groupe de ressources permettent d'identifier le texte de sortie à traduire, et de fournir des valeurs dans différentes langues. Les clés sont définies automatiquement pour les noms de conversation d'intention, les réponses des intentions de réponse et certaines propriétés communes. Toutefois, vous devez créer des clés vous-même pour les autres textes de sortie à traduire, comme le texte de votre flux de dialogue.

Pour créer des entrées de groupe de ressources, procédez comme suit :

Dans la barre de navigation de gauche de la brique, cliquez sur .
Cliquez sur l'onglet Défini par l'utilisateur.
Cliquez sur Ajouter un groupe.

La boîte de dialogue Créer une entrée apparaît, ce qui vous permet de créer votre première entrée dans la langue principale de la brique.
Entrez une clé (que vous utilisez pour référencer l'entrée de groupe) et le texte correspondant. Par exemple, pour l'invite utilisateur How old are you?, vous pouvez entrer HowOld dans le champ Clé, puis How old are you? dans le champ Texte.
Pour Annotation, entrez les informations qui seront utiles à ceux qui devront éventuellement faire référence à l'entrée ultérieurement, comme les traducteurs.
Cliquez sur Créer une entrée.

Ajout d'une langue à une clé de groupe de ressources

Lorsque vous créez une clé de groupe, sa valeur de texte initiale correspond à la valeur par défaut de la brique (langue principale ou prédominante).

Afin d'ajouter du texte pour une clé de groupe dans une autre langue, procédez comme suit :

Sélectionnez la clé, puis cliquez sur Ajouter une langue.
Renseignez les champs de la boîte de dialogue Créer une entrée avec les informations suivantes :
- Langue : saisissez ou sélectionnez une balise de langue IETF BCP 47 telle que fr pour le français ou de pour l'allemand.
- Texte : chaîne de sortie. Par exemple, pour une traduction française (fr) de la clé HowOld, ajoutez une chaîne telle que quel âge avez-vous ?

Remarque

Vous pouvez également utiliser des environnements locaux plus spécifiques (tels que en-US), mais ils ne sont pas utiles dans la plupart des cas. Par exemple, si vous utilisez un service de traduction pour détecter la langue, seul un code à deux lettres sera renvoyé.

Si la brique ne parvient pas à mettre en correspondance la langue d'entrée avec une des balises de langue définies dans le groupe, elle opte par défaut pour une balise moins spécifique (si disponible). Si aucune des entrées ne correspond à la langue du navigateur, la brique utilise l'entrée par défaut, à savoir l'anglais. Pour plus de détails, reportez-vous à Résolution d'une entrée de groupe de ressources.

Traduction du nom de la conversation

A certains moments d'une conversation, par exemple lorsque la brique tente de déterminer le flux que l'utilisateur veut suivre, la brique peut afficher un dialogue faisant référence à des intentions. Dans ce cas, la brique fait référence aux intentions avec leur nom de conversation, pour lesquelles des clés et des entrées par défaut sont générées dans le groupe de ressources.

Pour fournir une traduction à un nom de conversation, procédez comme suit :

Cliquez sur Groupe de ressources dans la barre de navigation de gauche ().
Cliquez sur l'onglet Intentions sur la page Groupes de ressources.

description de l'illustration rb-conversation-name.png
Sélectionnez l'intention.
Cliquez sur Ajouter une langue.
Renseignez les champs de la boîte de dialogue Créer une entrée avec les informations suivantes :
- Langue : ajoutez une balise de langue IETF BCP 47 telle que fr pour le français, de pour l'allemand ou en-US pour l'anglais américain.
- Texte : chaîne de sortie. Par exemple, pour une traduction française (fr) de la clé HowOld, ajoutez une chaîne telle que quel âge avez-vous ?

Remarque

Si l'intention dont vous voulez modifier le nom de conversation n'apparaît pas dans la liste, cliquez sur

pour revenir sur la page Intentions, puis sélectionnez l'intention et modifiez le champ Nom de la conversation. Lorsque vous revenez sur la page Groupes de ressources, ce nom doit apparaître dans l'onglet Intentions.

Traduction des réponses pour les intentions de réponse

Lorsque vous créez une intention de réponse, une clé de groupe de ressources est automatiquement créée pour la réponse.

Afin de fournir une traduction pour une réponse dans une intention de réponse, procédez comme suit :

Cliquez sur Groupe de ressources dans la barre de navigation de gauche ().
Cliquez sur l'onglet Question/réponses sur la page Groupes de ressources.
Sélectionnez la clé de la réponse à traduire.
Cliquez sur Ajouter une langue.
Renseignez les champs de la boîte de dialogue Créer une entrée avec les informations suivantes :
- Langue : ajoutez une balise de langue IETF BCP 47 telle que fr pour le français, de pour l'allemand ou en-US pour l'anglais américain.
- Texte : chaîne de sortie.

Référencement des groupes de ressources dans le flux de dialogue

Pour définir la sortie d'un composant intégré, vous devez référencer la clé de message via la variable rb (qui est réservée aux groupes de ressources).

Voici une expression simple qui référence une clé de groupe appelée WhatType pour renvoyer une chaîne simple :

${rb('WhatType')}

Voici une expression qui utilise des valeurs dynamiques. Il fait référence à une clé de package appelée OnTheWay, où size.value et type.value sont les arguments de la clé OnTheWay.


${rb('OnTheWay','${size.value}','${type.value}')}

Vous pouvez également créer des entrées de groupe avec des formats de message plus complexes pour gérer les cas de pluriel et autres. Reportez-vous aux rubriques suivantes pour en savoir plus sur la plage de formats de message et sur la façon de les référencer dans votre flux de dialogue.

Conseil :

Pour tester les groupes de ressources à l'aide du testeur, définissez votre navigateur sur une autre langue.

Formats de message

Plusieurs formats sont disponibles pour vos messages de groupe de ressources afin de gérer tous les aspects, du renvoi de messages statiques à l'assemblage de messages en fonction de plusieurs variables.

Messages simples

Pour les messages statiques simples :

En tant que valeur de la clé de groupe, indiquez du texte brut. Par exemple : This is the value of my bundle key
Dans le flux de dialogue ou la propriété de configuration, référencez la clé de groupe au format suivant : {rb.bundleKey} ou {rb('bundleKey')}

Exemple : message simple

Voici un exemple sans paramètre.

Clé de groupe de ressources : pizzaOnTheWay
Message de groupe de ressources : Your pizza is on the way.
Expression qui référence la clé de groupe de ressources : ${rb('pizzaOnTheWay')} (ou ${rb.pizzaOnTheWay})

Messages avec paramètres

Pour les messages avec des variables :

En tant que valeur de la clé de groupe, fournissez du texte et incluez des paramètres dans l'un des formats suivants :
- Paramètres nommés sous la forme {parameterName}
- Paramètres numérotés de façon séquentielle en commençant par {0}
Dans le flux de dialogue ou la propriété de configuration, référencez la clé de groupe au format suivant :
```
${rb('bundleKey','variable1','variable2',...)}
```

Exemple : message avec paramètres nommés

Voici un exemple avec deux paramètres nommés :

Clé de groupe de ressources : pizzaOnTheWayWithNamedParams
Message de groupe de ressources (en anglais) :
```
Your {pizzaSizeParam} {pizzaTypeParam} pizza is on the way.
```
(où {pizzaSizeParam} et {pizzaTypeParam} sont des paramètres pour les valeurs à résoudre et à insérer lors de la conversation)
Expression qui référence la clé de groupe de ressources :
```
${rb('pizzaOnTheWayWithNamedParams','pizzaSizeParam,pizzaTypeParam',pizzaSize.value,
      pizzaType.value)}
```
(où pizzaSize et pizzaType sont des variables définies dans le flux de dialogue)

Exemple : message avec paramètres numérotés

Voici un exemple d'utilisation de paramètres numérotés :

Clé de groupe de ressources : pizzaOnTheWayWithNumberedParams
Message de groupe de ressources :
```
Your {0} {1} pizza is on the way.
```
(où {0} et {1} sont les paramètres des valeurs à résoudre et à insérer lors de la conversation)
Expression qui référence la clé de groupe de ressources :
```
${rb('pizzaOnTheWayWithNumberedParams',pizzaSize.value, pizzaType.value)}
```
(où pizzaSize et pizzaType sont des variables définies dans le flux de dialogue)

Messages complexes

Vous pouvez également créer des messages complexes, dans lesquels la valeur de variables peut modifier le texte de sortie environnant. Par exemple, si la réponse inclut une variable pour le nombre de pizzas commandées, vous pouvez utiliser un message complexe afin de déterminer si le singulier ("pizza") ou le pluriel ("pizzas") est à employer.

Conseil :

Lorsque vous composez des entrées de groupe complexes, vous pouvez utiliser ce testeur pour vous assurer que les entrées sont résolues comme prévu :https://format-message.github.io/icu-message-format-for-translators/editor.html.

Messages gérant le singulier et le pluriel

Pour les messages incluant une variable qui exprime une quantité, vous devrez peut-être faire varier la formulation du message final en fonction de la résolution de la variable. Pour certaines langues, il se peut également que vous deviez aller plus loin qu'une simple distinction singulier/pluriel. Pour gérer les messages avec des variables de quantité, vous pouvez utiliser un argument plural dans la valeur de la clé afin d'indiquer les différentes façons de construire le message.

Dans un argument plural, une partie du message est déterminée par une valeur numérique, ainsi que par les règles de grammaire de la langue concernée. Vous définissez le texte du message pour différents cas, en fonction de la résolution de l'argument plural. Il existe plusieurs cas prédéfinis, tels que one, two, few, many et other. Vous pouvez également définir un cas pour un nombre spécifique en ajoutant = avant ce nombre (par exemple, =3). Tous les cas prédéfinis ne sont pas pertinents dans toutes les langues. Par exemple, pour l'anglais, vous pouvez simplement utiliser =0, =1 et other.

Vous devez toujours inclure un cas et un message pour other. Pour inclure le nombre résolu dans le texte du message d'un cas, utilisez # afin de générer le nombre.

Lorsque vous utilisez des arguments plural, le format ressemble généralement à ce qui suit :

{plural_arg_name, plural,
=0 {Text used when the plural argument resolves to 0}
=1 {Text used when the plural argument resolves to 1}
other {Text used when the plural argument resolves to a value that doesn't match the other cases (in this case 0 or 1)}
}

Dans l'exemple ci-dessus, 0, 1 et other sont les quantités possibles. Pour plus de détails sur le fonctionnement des types d'argument plural, reportez-vous à la spécification de balisage des données d'environnement local Unicode.

Pour plus de détails sur la prise en charge du pluriel de différentes langues, reportez-vous aux règles de pluriel des langues unicode.org.

Autres messages complexes

Si le contenu du message doit être basé sur d'autres conditions, vous pouvez utiliser un argument select avec des mots-clés que vous définissez pour assembler le message.

{select_arg_name, select,
keyword1 {Text used when the select argument resolves to keyword1}
keyword2 {Text used when the select argument resolves to keyword2}
other {Text used when the plural argument resolves to a value that doesn't match the other keywords}
}

Vous pouvez également imbriquer des arguments plural et select :

{select_arg_name, select,
keyword1 {
{plural_arg_name, plural,
=0{Text used when the select argument resolves to keyword1 and the plural argument resolves to 0.}
=1 {Text used when the select argument resolves to keyword1 and the plural argument resolves to 1}
other {Text used when the select argument resolves to keyword1 and the plural argument resolves to a value that doesn't match the other cases (in this case 0 or 1)}}}
keyword2 {
{plural_arg_name, plural,
=0 {Text used when the select argument resolves to keyword2 and the plural argument resolves to 0.}
=1 {Text used when the select argument resolves to keyword2 and the plural argument resolves to 1}
other {Text used when the select argument resolves to keyword2 and the plural argument resolves to a value that doesn't match the other cases (in this case 0 or 1)}}}
other {
{plural_arg_name, plural,
=0 {Text used when the select argument resolves to other and the plural argument resolves to 0.}
=1 {Text used when the select argument resolves to other and the plural argument resolves to 1}
other {Text used when the select argument resolves to other and the plural argument resolves to a value that doesn't match the other cases (in this case 0 or 1)}}}
}

Remarque

Pour les noms de mot-clé, vous devez utiliser uniquement des caractères alphabétiques ASCII (A-Z, a-z).

Vous trouverez plus de détails sur les messages complexes à l'adresse https://unicode-org.github.io/icu/userguide/format_parse/messages/#complex-argument-types.

Faire référence à des messages complexes

Vous pouvez référencer des messages de regroupement de ressources complexes de l'une des deux manières suivantes :

A l'aide d'une variable de correspondance où les valeurs de chacun des paramètres sont assemblées :
```
${rb('bundleKey', formatMap.value)}
```
En incluant un argument de liste avec les noms de paramètre suivis d'arguments pour chaque valeur :
```
${rb('bundleKey', 'param1, param2, param3', paramValue1, paramValue2, paramValue3)}
```
Remarque

Lorsque les valeurs de paramètre sont des chaînes, elles doivent être placées entre apostrophes (').

Pour plus d'informations, reportez-vous à la rubrique Types d'argument complexes dans la documentation ICU.

Correspondances des valeurs de groupe de ressources complexes

Si vous décidez d'utiliser une variable de correspondance pour assembler les paramètres d'un message complexe, procédez comme suit :

Définissez une variable de type Map et donnez-lui une valeur au format JSON valide. Par exemple, la valeur d'une entrée de bundle de pizzas peut ressembler à ce qui suit :
```
{
    "pizzaSize": "${pizzaSize.value}",
    "pizzaType:": "${pizzaType.value}",
    "count": "${pizzaNum.value}"
}
```
Remarque

Dans les flux de dialogue basés sur YAML, vous devez d'abord déclarer la variable dans le noeud context, puis utiliser un composant System.SetVariable pour définir sa valeur avec une syntaxe semblable à la suivante :
```
  populateMap:
    component: "System.SetVariable"
    properties:
      variable: "formatMap"
      value:
        pizzaSize: "${pizzaSize.value}"
        pizzaType: "${pizzaType.value}"
        count: "${pizzaNum.value}"
```
Dans l'expression dans laquelle vous référencez la clé de groupe, incluez la correspondance en tant qu'argument. Par exemple :
```
${rb('pizzaOnTheWaySingularOrPlural', formatMap.value)}
```

Exemple : message qui gère les variantes singulier/pluriel

Voici un exemple d'entrée de groupe de ressources pour un message dont le contenu peut être au singulier ou au pluriel :

Clé de groupe de ressources : pizzaOnTheWaySingularOrPlural

Message de groupe de ressources (en anglais) :

{count, plural,
=0 {No pizzas will be delivered.}
=1 {Your {pizzaSizeParam} {pizzaTypeParam} pizza is on the way.}
other {# pizzas are on the way.}
}

Expression qui référence la clé de groupe de ressources :
```
${rb('pizzaOnTheWaySingularOrPlural','count, pizzaSizeParam, pizzaTypeParam', 'pizzaNum.value, pizzaSize.value, pizzaType.value')}
```
Comme vous pouvez le constater, l'expression contient deux arguments :
- Liste des noms de paramètre (count, pizzaSizeParam, pizzaTypeParam)
- Liste des valeurs de ces paramètres (pizzaNum.value, pizzaSize.value, pizzaType.value)

Exemple : message avec paramètres imbriqués

{ gender, select,
female
{{count, plural,
=0 {She has not ordered anything.}
=1 {She has ordered only one.}
other {She has ordered #.}}}
male
{{count, plural,
=0 {He has not ordered anything.}
=1 {He has ordered only one.}
other {He has ordered #.}}}
other
{{count, plural,
=0 {They have not ordered anything.}
=1 {They have ordered only one.}
other {They have ordered #.}}}}

Voici les variantes de résolution de ce message :

Elle n'a rien commandé.
Elle n'en a commandé qu'une seule.
Elle en a commandé 2.
Il n'a rien commandé.
Il n'en a commandé qu'une seule.
Il en a commandé 2.
Ils n'ont rien commandé.
Ils n'en ont commandé qu'une seule.
Ils en ont commandé 2.

Remarque

2 est le nombre résolu par l'argument count dans l'exemple ci-dessus, mais il peut s'agir de n'importe quel nombre différent de 0 et 1.

Groupes de ressources et traduction automatique des briques

Voici la procédure générale de configuration d'une brique en vue du recours à un service de traduction uniquement pour les saisies utilisateur avec des groupes de ressources pour les réponses de la brique :

Si vous ne l'avez pas encore fait, ajoutez un service de traduction à votre brique.
Utilisez le composant Détecter langue pour déterminer la langue de la saisie utilisateur.
Appliquez des groupes de ressources pour gérer les réponses de la brique à l'utilisateur.
Pour tous les composants qui référencent des groupes de ressources, assurez-vous que la sortie n'est pas traduite automatiquement.
- Pour les briques développées en mode de boîte de dialogue visuelle, définissez la propriété Traduire le message de réponse de bot de la page Paramètres de la brique sur False.
- Pour les briques développées en mode de dialogue YAML, vous pouvez les gérer de manière globale dans la brique en définissant la variable de contexte autoTranslate de manière à traduire l'entrée et non la sortie. Par exemple :
```
  setAutoTranslate:
    component: "System.SetVariable"   
    properties:
      variable: "autoTranslate"     
      value:
       input: true
       output: false
```

Remarque

Pour les briques développées en mode YAML, vous pouvez également gérer ce problème au niveau du composant en utilisant la propriété translate de chaque composant sans définir la variable autoTranslate. Par exemple, pour configurer la traduction automatique de l'entrée d'un composant System.Text et désactiver la traduction automatique de sa sortie, vous pouvez adopter l'approche suivante :

  askName:
    component: "System.Text"
    properties:   
      prompt: "${rb.askNamePrompt}"
      variable: "name"
      translate:       
        input: true
        output: false

Si votre brique utilise des groupes de ressources pour certains composants, mais repose sur la traduction automatique pour d'autres composants, vous pouvez adopter l'approche suivante :

Définissez la variable de contexte autoTranslate sur true.
Comme dans l'exemple de code ci-dessus, définissez la propriété translate:input sur false pour chaque composant qui utilise un groupe de ressources.

Traduction automatique conditionnelle

Si vous avez défini des groupes de ressources pour certaines langues mais que vous voulez également pouvoir fournir des réponses dans les langues pour lesquelles vous ne disposez d'aucune entrée de groupe de ressources, vous pouvez utiliser des expressions FreeMarker pour déterminer la résolution des paramètres Message d'entrée utilisateur de traduction et Message de réponse de bot de traduction (pour les briques Visual Flow Designer) et autotranslate et translate (pour les briques basées sur YAML).

Par exemple, si des groupes de ressources sont définis uniquement pour l'anglais et le néerlandais, vous pouvez activer la traduction conditionnelle de la sortie pour les autres langues. Voici à quoi pourrait ressembler cette expression :

${profile.languageTag!='en'&& profile.languageTag!='nl'}

Résolution d'entrées de groupe de ressources

Le groupe de ressources appliqué dépend de la valeur stockée pour les deux variables de profil utilisateur propres à l'emplacement : profile.languageTag et profile.locale. Si les deux variables sont définies, profile.languageTag est prioritaire.

Lors de la résolution de la langue à utiliser, Oracle Digital Assistant recherche d'abord une correspondance exacte. S'il n'en trouve pas, il élargit sa recherche de façon incrémentielle jusqu'à ce qu'elle aboutisse. S'il ne trouve toujours pas de correspondance, il renvoie la langue par défaut, à savoir l'anglais (en).

Par exemple, si la valeur ${profile.locale} est définie sur en-AU-sydney (et si profile.languageTag n'est pas défini), Oracle Digital Assistant effectue les opérations suivantes afin de trouver la meilleure correspondance de langue :

Il effectue une recherche dans le groupe avec les critères de langue, de pays et de variante (en-AU-sydney).
S'il ne trouve aucun résultat, il effectue une recherche dans le groupe avec les critères de langue et de pays (en-AU).
En cas d'échec, il élargit sa recherche à la seule langue (en).

Remarque

profile.locale prend en charge les valeurs au format ISO langue-pays ou ISO language_country.

Export et import de groupes de ressources

Vous pouvez exporter et importer des groupes de ressources sous forme de fichier CSV, ce qui vous permet de travailler sur les groupes hors ligne.

Le fichier CSV doit comporter les colonnes suivantes :

languageTag
key
message
annotation

Pour exporter un fichier CSV avec le groupe de ressources existant, procédez comme suit :

Sur la page Groupe de ressources pour votre brique ou votre assistant numérique, cliquez sur pour exporter un fichier CSV avec le groupe de ressources existant.

Même si vous n'avez pas encore ajouté de clés au groupe de ressources, un fichier avec le format CSV requis est exporté.

Pour importer un fichier de groupe de ressources, procédez comme suit :

Sur la page Groupe de ressources pour votre brique ou votre assistant numérique, cliquez sur .

Documentation Oracle Cloud Infrastructure