Grupos de recursos para las aptitudes

Si la aptitud está diseñada para manejar varios idiomas y desea controlar la redacción de las respuestas de la aptitud, utilice grupos de recursos. Puede proporcionar grupos de recursos para tantos idiomas y dialectos como sea necesario.

Incluso si la aptitud está dirigida al solo idioma, el uso de paquetes de recursos tiene ventajas, como permitirle colocar todo el texto orientado al usuario en un único lugar.

Hay una serie de opciones para parametrizar entradas de grupos de recursos, lo que permite embeber variables en las cadenas. Además, puede utilizar el formato de ICU para las entradas del grupo para ayudar a redactar una respuesta según cómo se resuelvan sus parámetros. Esto le permite hacer cosas como ajustar la redacción según si algo es singular o plural.

Tipos de claves de grupos de recursos

Las cadenas orientadas al usuario de una aptitud provienen de varias partes de la aptitud. En algunos casos, se crea automáticamente una clave de grupo de recursos. En otros casos, no se genera ninguna clave, pero puede definirla usted mismo.

Estos son los lugares desde donde se originan las cadenas orientadas al usuario y cómo puede gestionarlas en el grupo de recursos.

El campo Nombre de conversación para las intenciones.
Al definir nombres de conversación, las claves de grupos de recursos se crean automáticamente y se rellenan con el valor definido para el idioma por defecto. Puede acceder a las claves del grupo para los nombres de conversación haciendo clic en y seleccionando el separador Intenciones.
El campo Respuesta para intenciones (intenciones de respuesta).
Al definir respuestas en intenciones, las claves del grupo de recursos se crean automáticamente y se rellenan con el texto de respuesta en el idioma por defecto. Puede acceder a las claves del grupo para las respuestas haciendo clic en y seleccionando el separador Q&A.
La configuración de la aptitud (a la que puede acceder haciendo clic en y seleccionando el separador Configuración).
Para esta configuración, las claves del grupo de recursos se generan con valores por defecto y los valores de configuración se expresan como referencias a las claves del grupo de recursos. Puede editar los valores de estas claves haciendo clic en y seleccionando el separador Configuración.
Peticiones de datos, etiquetas y mensajes por defecto integrados en los componentes del flujo de diálogo estándar.
Si desea cambiar el valor por defecto de cualquiera de estas propiedades, puede hacerlo dentro del grupo de recursos haciendo clic en y seleccionando el separador Configuración.

No necesita agregar la propiedad al componente en la definición del flujo de diálogo para hacer referencia al valor actualizado del grupo de recursos.

Si desea cambiar el valor de una de esas propiedades para un componente en un estado determinado sin cambiar el valor por defecto, agregue la propiedad al componente en ese estado.
Cadenas de flujo de diálogo. Para el texto que incorpora a sus componentes, puede definir sus propias claves de grupo de recursos y, a continuación, hacer referencia a esas claves desde la definición del flujo de diálogo.
Puede crear y editar estas claves haciendo clic en y seleccionando el separador Definido por el usuario.
Peticiones de datos y mensajes de las definiciones de entidad. Para estas cadenas, puede definir sus propias claves de grupo de recursos y, a continuación, hacer referencia a esas claves desde los campos para estas propiedades en la definición de entidad.
Puede crear y editar claves para estas cadenas haciendo clic en y seleccionando el separador Definido por el usuario.

Nota

Los grupos de recursos no son el mecanismo para traducir entidades de lista de valores. En su lugar, proporcione la traducción en la definición de entidad personalizada. Para las aptitudes que utilizan idiomas con soporte nativo, debe proporcionar valores para ese idioma nativo. Para las aptitudes basadas en un servicio de traducción, debe proporcionar los valores traducidos como sinónimos de los valores en el idioma por defecto.

Creación de claves de grupo de recursos

Las claves de grupo de recursos se utilizan para identificar el texto de salida que se debe traducir y proporcionar valores en uno o más idiomas. Las claves se definen automáticamente para los nombres de conversación de intención, las respuestas para las intenciones de respuesta y algunas propiedades comunes. Sin embargo, usted debe crear claves para otro texto de salida que desee traducir, como texto del flujo de diálogo.

Para crear entradas de grupos de recursos:

En la navegación de la izquierda de la aptitud, haga clic en .
Haga clic en el separador Definido por el usuario.
Haga clic en Agregar grupo.

Aparece el cuadro de diálogo Crear entrada, que permite crear su primera entrada en el idioma principal de la aptitud.
Introduzca la clave (que se utiliza para hacer referencia a la entrada del grupo) y el texto correspondiente. Por ejemplo, para la petición de datos de usuario How old are you?, puede introducir HowOld en el campo Clave y, a continuación. How old are you? en el campo Texto.
Para Anotación, introduzca cualquier información que sea útil para aquellos que puedan necesitar hacer referencia a la entrada más adelante, como los traductores.
Haga clic en Crear entrada.

Adición de un idioma a una clave de paquete de recursos

Al crear una clave de grupo, su valor de texto inicial es para el idioma por defecto de la aptitud (es decir, el idioma principal o el predominante).

Para agregar texto para una clave de paquete en otro idioma:

Seleccione la clave y, a continuación, haga clic en Agregar idioma.
Complete el cuadro de diálogo Crear entrada:
- idioma: introduzca o seleccione una etiqueta de idioma IETF BCP 47 como, por ejemplo, fr para francés o de para alemán.
- Texto: cadena de salida. Por ejemplo, para una traducción al francés (fr) de la clave HowOld, debe agregar una cadena como quel âge avez-vous?

Nota

También puede utilizar configuraciones regionales más específicas (como en-US), pero, en la mayoría de los casos, no son útiles. Por ejemplo, si está utilizando un servicio de traducción para detectar el idioma, solo se devolverá un código de dos letras.

Si la aptitud no puede parear el idioma de entrada con una etiqueta de idioma definida en el grupo, se establece por defecto en una etiqueta menos específica (si hay alguna disponible). Si ninguna de las entradas coincide con el idioma del explorador, la aptitud utiliza la entrada por defecto, inglés. Consulte Resolución de entrada de grupo de recursos para obtener más información.

Traducción del nombre de conversación

En algunos puntos de una conversación, como cuando la aptitud intenta determinar qué flujo quiere seguir el usuario, la aptitud puede presentar un cuadro de diálogo que hace referencia a una o varias intenciones. En estos casos, la aptitud hace referencia a las intenciones por sus nombres de conversación, para los que se generan claves y entradas por defecto en el grupo de recursos.

Para proporcionar una traducción para un nombre de conversación:

Haga clic en Grupo de recursos en la barra de navegación izquierda ().
Haga clic en el separador Intenciones de la página Grupos de recursos.

Descripción de la ilustración rb-conversation-name.png
Seleccione la intención
Haga clic en Agregar idioma.
Complete el cuadro de diálogo Crear entrada:
- Idioma: agregue una etiqueta de idioma IETF BCP 47 como, por ejemplo, fr para francés, de para alemán o en-US para inglés estadounidense.
- Texto: cadena de salida. Por ejemplo, para una traducción al francés (fr) de la clave HowOld, debe agregar una cadena como quel âge avez-vous?

Nota

Si la intención cuyo nombre de conversación quiere cambiar no aparece en la lista, haga clic en

para volver a la página Intenciones, seleccione la intención y edite el campo Nombre de conversación. Al volver a la página Grupos de recursos, debería aparecer bajo el separador Intenciones.

Traducción de las respuestas para intenciones de respuesta

Al crear una intención de respuesta, se crea automáticamente una clave de grupo de recursos para la respuesta.

Para proporcionar una traducción de una respuesta en una intención de respuesta:

Haga clic en Grupo de recursos en la barra de navegación izquierda ().
Haga clic en el separador Preguntas y respuestas de la página Grupos de recursos.
Seleccione la clave para la respuesta que desea traducir.
Haga clic en Agregar idioma.
Complete el cuadro de diálogo Crear entrada:
- Idioma: agregue una etiqueta de idioma IETF BCP 47 como, por ejemplo, fr para francés, de para alemán o en-US para inglés estadounidense.
- Texto: cadena de salida.

Grupos de recursos de referencia en el flujo de diálogo

Para definir la salida de un componente incorporado, haga referencia a la clave del mensaje mediante la variable rb (que está reservada para grupos de recursos).

Esta es una expresión simple que hace referencia a una clave de grupo denominada WhatType para devolver una cadena simple:

${rb('WhatType')}

Esta es una expresión que utiliza valores dinámicos. Hace referencia a una clave de grupo denominada OnTheWay, donde size.value y type.value son los argumentos de la clave OnTheWay.


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

También puede crear entradas de grupo con formatos de mensaje más complejos para manejar plurales y otros casos. Consulte los siguientes temas para obtener más información sobre el rango de formatos de mensaje y cómo hacer referencia a ellos en el flujo de diálogo.

Consejo:

Para probar los grupos de recursos utilizando el comprobador, configure el explorador en otro idioma.

Formatos de mensaje

Existen varios formatos que puede utilizar para los mensajes de grupos de recursos a fin de gestionar todo, desde la devolución de mensajes estáticos hasta el ensamblaje de mensajes según varias variables.

Mensajes simples

Para mensajes estáticos simples:

Como valor para la clave de grupo, proporcione texto sin formato. Por ejemplo: This is the value of my bundle key
Desde el flujo de diálogo o la propiedad de configuración, haga referencia a la clave del grupo con el formato: {rb.bundleKey} o {rb('bundleKey')}

Ejemplo de mensaje simple

A continuación, se muestra un ejemplo sin parámetros.

Clave de grupo de recursos: pizzaOnTheWay
Mensaje de grupo de recursos: Your pizza is on the way.
Expresión para hacer referencia a la clave de grupo de recursos: ${rb('pizzaOnTheWay')} (o ${rb.pizzaOnTheWay})

Mensajes con parámetros

Para mensajes con variables:

Como valor para la clave de grupo, proporcione texto e incluya parámetros con uno de los siguientes formatos:
- Parámetros con nombre con el formato {parameterName}
- Parámetros numerados secuencialmente que comienzan con {0}
Desde el flujo de diálogo o la propiedad de configuración, haga referencia a la clave del grupo con el formato:
```
${rb('bundleKey','variable1','variable2',...)}
```

Ejemplo: mensaje con parámetros con nombre

A continuación se muestra un ejemplo con dos parámetros con nombre:

Clave de grupo de recursos: pizzaOnTheWayWithNamedParams
Mensaje de grupo de recursos (en inglés):
```
Your {pizzaSizeParam} {pizzaTypeParam} pizza is on the way.
```
(donde {pizzaSizeParam} y {pizzaTypeParam} son parámetros para los valores que se deben resolver e insertar durante la conversación)
Expresión para hacer referencia a la clave de grupo de recursos:
```
${rb('pizzaOnTheWayWithNamedParams','pizzaSizeParam,pizzaTypeParam',pizzaSize.value,
      pizzaType.value)}
```
(donde pizzaSize y pizzaType son variables definidas en el flujo de diálogo)

Ejemplo: mensaje con parámetros numerados

A continuación se muestra un ejemplo con parámetros numerados:

Clave de grupo de recursos: pizzaOnTheWayWithNumberedParams
Mensaje de grupo de recursos:
```
Your {0} {1} pizza is on the way.
```
(donde {0} y {1} son parámetros para los valores que se deben resolver e insertar durante la conversación)
Expresión para hacer referencia a la clave del grupo de recursos:
```
${rb('pizzaOnTheWayWithNumberedParams',pizzaSize.value, pizzaType.value)}
```
(donde pizzaSize y pizzaType son variables definidas en el flujo de diálogo)

Mensajes complejos

También puede crear mensajes complejos, donde el valor de una o más variables puede afectar al texto de salida circundante. Por ejemplo, si la respuesta incluye una variable para el número de pizzas pedidas, puede utilizar un mensaje complejo para determinar si utilizar el singular ("pizza") o el plural ("pizzas").

Consejo:

Al crear entradas de grupos complejos, puede usar este probador para asegurarse de que las entradas se resuelvan como desea:https://format-message.github.io/icu-message-format-for-translators/editor.html.

Mensajes que gestionan tanto el singular como el plural

Para los mensajes que incluyen una variable que expresa una cantidad de algo, puede que necesite cambiar la redacción del mensaje ensamblado en función de cómo se resuelva la variable. Y para algunos idiomas, es posible que necesite realizar una adaptación que implique más que una simple distinción entre singular o plural. Para gestionar mensajes con variables de cantidad, puede utilizar un argumento plural en el valor de la clave para especificar las diferentes formas en las que puede que sea necesario crear el mensaje.

En un argumento plural, parte del mensaje viene determinado por un valor numérico junto con reglas de gramática para el idioma especificado. Usted definirá el texto del mensaje para distintos casos, según cómo se resuelva el argumento plural. Hay varios casos predefinidos, como one, two, few, many y other. También puede especificar un caso para un número específico anteponiendo = a ese número (por ejemplo, =3). No todos los casos predefinidos son relevantes para cada idioma. Por ejemplo, para inglés, podría simplemente utilizar =0, =1 y other.

Siempre debe incluir un caso y un mensaje para other. Para incluir el número resuelto en el texto del mensaje para un caso, utilice # para generar el número.

Cuando se utilizan argumentos en plural, el formato suele tener un aspecto similar al siguiente:

{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)}
}

En el ejemplo anterior, 0, 1 y other son las posibles cantidades. Puede encontrar más detalles sobre cómo funcionan los tipos de argumentos plurales en la especificación Unicode Locale Data Markup Language.

Para obtener detalles sobre el soporte de plural para varios idiomas, consulte las reglas de idioma plural unicode.org.

Otros mensajes complejos

Si el contenido del mensaje se debe basar en otras condiciones, puede utilizar un argumento select con palabras clave que defina para ensamblar el mensaje.

{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}
}

También puede anidar argumentos plurales y seleccionados:

{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)}}}
}

Nota

Para los nombres de palabras clave, solo debe utilizar caracteres alfabéticos ASCII (A-Z, a-z).

Puede encontrar más información sobre los mensajes complejos en https://unicode-org.github.io/icu/userguide/format_parse/messages/#complex-argument-types.

Referencia a mensajes complejos

Puede hacer referencia a mensajes de grupos de recursos complejos de una de las dos formas siguientes:

Utilizando una variable de asignación donde se ensamblen los valores de cada uno de los parámetros:
```
${rb('bundleKey', formatMap.value)}
```
Incluir un argumento de lista con los nombres de parámetros seguidos de argumentos para cada valor:
```
${rb('bundleKey', 'param1, param2, param3', paramValue1, paramValue2, paramValue3)}
```
Nota

Cuando los valores de parámetros son cadenas, se deben incluir entre comillas simples (').

Para obtener más información, consulte el tema Tipos de argumentos complejos en la documentación de ICU.

Variables map para valores de grupos de recursos complejos

Si decide utilizar la variable map para ensamblar los parámetros de un mensaje complejo, esto es lo que hace:

Defina una variable de tipo asignación y proporcione un valor en formato JSON válido. Por ejemplo, el valor de una entrada de paquete de pizza puede tener un aspecto similar al siguiente:
```
{
    "pizzaSize": "${pizzaSize.value}",
    "pizzaType:": "${pizzaType.value}",
    "count": "${pizzaNum.value}"
}
```
Nota

En los flujos de diálogo basados en YAML, primero declare la variable en el nodo context y, a continuación, utilice un componente System.SetVariable para definir su valor con una sintaxis como la siguiente:
```
  populateMap:
    component: "System.SetVariable"
    properties:
      variable: "formatMap"
      value:
        pizzaSize: "${pizzaSize.value}"
        pizzaType: "${pizzaType.value}"
        count: "${pizzaNum.value}"
```
En la expresión donde se haga referencia a la clave del grupo, incluya la asignación como argumento. Por ejemplo:
```
${rb('pizzaOnTheWaySingularOrPlural', formatMap.value)}
```

Ejemplo: mensaje que maneja variantes singulares y plurales

A continuación, se muestra un ejemplo de una entrada de grupo de recursos para un mensaje que podría tener contenido singular o plural:

Clave de grupo de recursos: pizzaOnTheWaySingularOrPlural

Mensaje de grupo de recursos (en inglés):

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

Expresión para hacer referencia a la clave del grupo de recursos:
```
${rb('pizzaOnTheWaySingularOrPlural','count, pizzaSizeParam, pizzaTypeParam', 'pizzaNum.value, pizzaSize.value, pizzaType.value')}
```
Como puede ver, la expresión contiene dos argumentos:
- Una lista de nombres de parámetros (count, pizzaSizeParam, pizzaTypeParam)
- Una lista de valores para esos parámetros (pizzaNum.value, pizzaSize.value, pizzaType.value)

Ejemplo: mensaje con parámetros anidados

{ 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 #.}}}}

Estas son las variaciones de cómo se puede resolver el mensaje:

Ella no ha pedido nada.
Ella solo ha pedido una.
Ella ha pedido 2.
Él no ha pedido nada.
Él solo ha pedido una.
Él ha pedido 2.
No han pedido nada.
Solo han pedido una.
Han pedido 2.

Nota

2 se indica en el ejemplo anterior como el número resuelto por el argumento count, pero podría ser cualquier número distinto de 0 o 1.

Grupos de recursos y traducción automática de aptitudes

Estos son los pasos generales para configurar una aptitud para usar un servicio de traducción solo para entradas del usuario cuando se utilizan grupos de recursos para las respuestas de la aptitud:

Si aún no lo ha hecho, agregue un servicio de traducción a la aptitud.
Utilice el componente Detectar Idioma para determinar el idioma de la entrada del usuario.
Aplique los grupos de recursos para manejar las respuestas de la aptitud al usuario.
Para los componentes que hagan referencia a grupos de recursos, asegúrese de que la salida no se traduzca automáticamente.
- Para las aptitudes desarrolladas en modo de cuadro de diálogo visual, defina la propiedad Convertir mensaje de respuesta de bot en la página Configuración de la aptitud en False.
- Para las aptitudes desarrolladas en el modo de diálogo YAML, puede manejar esto de forma global en la aptitud mediante la definición de la variable de contexto autoTranslate para traducir la entrada y no la salida. Por ejemplo:
```
  setAutoTranslate:
    component: "System.SetVariable"   
    properties:
      variable: "autoTranslate"     
      value:
       input: true
       output: false
```

Nota

Para las aptitudes desarrolladas en modo YAML, también puede manejar esta información en el nivel de componente mediante la propiedad translate de cada componente y no definiendo la variable autoTranslate. Por ejemplo, para configurar la traducción automática para la entrada de un componente System.Text y desactivar la traducción automática para su salida, puede hacer algo así:

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

Si la aptitud usa grupos de recursos para algunos componentes, pero se basa en la traducción automática para otros componentes, puede:

Establezca la variable de contexto autoTranslate en true.
Al igual que en el ejemplo de código anterior, defina la propiedad translate:input en false para cada componente que utilice un grupo de recursos.

Traducción automática condicional

Si ha definido grupos de recursos para algunos idiomas, pero también desea poder proporcionar respuestas para idiomas para los que no tiene entradas de grupos de recursos, puede utilizar expresiones FreeMarker para determinar cómo se resuelven las propiedades Mensaje de entrada de usuario de conversión y Mensaje de respuesta de bot de conversión (para aptitudes del diseñador de flujos visual) y autotranslate y translate (para aptitudes basadas en YAML).

Por ejemplo, si solo se definen grupos de recursos de holandés e inglés, puede activar condicionalmente la traducción de salida para los otros idiomas. Así es como podría ser esa expresión:

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

Resolución de entrada del grupo de recursos

El grupo de recursos que se aplica depende del valor almacenado para las dos variables de perfil de usuario específicas de la ubicación, profile.languageTag y profile.locale. Si se establecen ambas variables, profile.languageTag tiene prioridad.

Para resolver el idioma que utilizar, Oracle Digital Assistant busca en primer lugar una coincidencia exacta. Si no la encuentra, amplía incrementalmente la búsqueda hasta que lo consigue. Si sigue sin encontrar ninguna coincidencia, devuelve el idioma por defecto, que es el inglés (en).

Por ejemplo, si el valor de ${profile.locale} es en-AU-sydney (y profile.languageTag no se ha definido), Oracle Digital Assistant realiza las siguientes acciones para buscar la mejor coincidencia de idioma:

Busca en el grupo los criterios de idioma-país-variante (en-AU-sydney).
Si no obtiene resultados, busca en el grupo el idioma y el país (en-AU).
Si tampoco así obtiene resultados, amplía su búsqueda al idioma (en).

Nota

profile.locale soporta valores en formatos ISO de país de idioma o ISO language_country.

Exportación e importación de grupos de recursos

Puede exportar e importar grupos de recursos como formato de archivo CSV, lo que permite trabajar con los grupos fuera de línea.

El archivo CSV debe tener las siguientes columnas:

languageTag
key
message
annotation

Para exportar un archivo CSV con el grupo de recursos existente:

En la página Grupo de recursos de la aptitud o el asistente digital, haga clic en para exportar un archivo CSV con el grupo de recursos existente.

Incluso si aún no ha agregado ninguna clave al grupo de recursos, se exportará un archivo con el formato necesario del CSV.

Para importar un archivo de grupo de recursos:

En la página Grupo de recursos de la aptitud o el asistente digital, haga clic en .

Documentación de Oracle Cloud Infrastructure