Pacotes de Recursos para Habilidades

Se sua habilidade foi projetada para identificar vários idiomas e você quiser controlar a redação das respostas da sua habilidade, use pacotes de recursos. Você poderá fornecer pacotes de recursos para quantos idiomas e dialetos precisar.

Mesmo que sua habilidade seja direcionada para apenas um idioma, o uso de pacotes de recursos tem benefícios, como permitir que você coloque todo o texto de uso em um só lugar.

Há várias opções para parametrizar entradas de pacotes de recursos, o que permite incorporar variáveis nas strings. Além disso, você pode usar a formatação ICU para entradas de pacotes para ajudar a formular a redação de uma resposta, dependendo de como seus parâmetros são resolvidos. Isso permite que você ajuste a redação de acordo com singular ou plural.

Tipos de Chaves de Pacotes de Recursos

As strings voltadas ao usuário de uma habilidade vêm de várias partes da habilidade. Em alguns casos, uma chave de pacote de recursos é criada automaticamente para você. Em outros casos, nenhuma chave é gerada, mas você mesmo pode definir uma.

Aqui estão os locais de onde as strings voltadas ao usuário se originam e como você pode gerenciá-las no pacote de recursos.

O campo Nome da Conversa para intenções.
Quando você define nomes de conversa, as chaves de pacotes de recursos são criadas automaticamente e preenchidas com o valor que você definiu para o idioma padrão. Você pode acessar as chaves de pacotes para nomes de conversas clicando em e selecionando a guia Intenções.
O campo Resposta para intenções (de resposta).
Quando você define respostas em intenções, as chaves de pacotes de recursos são criadas automaticamente e preenchidas com o texto da resposta no idioma padrão. Você pode acessar as chaves de pacotes para respostas clicando em e selecionando a guia Perguntas e Respostas.
As definições de configuração da habilidade (que você acessa clicando em e selecionando a guia Configuração).
Para essas configurações, as chaves de pacotes de recursos são geradas com valores padrão e os valores de definição são expressos como referências às chaves de pacotes de recursos. Você pode editar os valores dessas chaves clicando em e selecionando a guia Configuração.
Prompts, labels e mensagens padrão incorporados nos componentes do fluxo de caixas de diálogo padrão.
Se quiser alterar o valor padrão de qualquer uma dessas propriedades, você poderá fazer isso dentro do pacote de recursos clicando em e selecionando a guia Configuração.

Você não precisa adicionar a propriedade ao componente na definição do fluxo de caixas de diálogo para fazer referência ao valor atualizado no pacote de recursos.

Se você quiser alterar o valor de uma dessas propriedades de um componente em um estado específico sem alterar o padrão, adicione a propriedade ao componente nesse estado.
Strings de fluxo de caixas de diálogo. Para texto incorporado aos seus componentes, você pode definir suas próprias chaves de pacotes de recursos e, em seguida, referenciar essas chaves na definição do fluxo de caixas de diálogo.
Você pode criar e editar essas chaves clicando em e selecionando a guia Definido pelo Usuário.
Prompts e mensagens de definições de entidade. Para essas strings, você pode definir suas próprias chaves de pacotes de recursos e, em seguida, fazer referência a essas chaves nos campos dessas propriedades na definição da entidade.
Você pode criar e editar chaves para essas strings clicando em e selecionando a guia Definido pelo Usuário.

Observação

Os pacotes de recursos não são o mecanismo para traduzir entidades de lista de valores. Em vez disso, você fornece a tradução dentro da definição de entidade personalizada. Para habilidades que usam idiomas suportados nativamente, você fornece valores para esse idioma nativo. Para habilidades baseadas em um serviço de tradução, você fornece os valores traduzidos como sinônimos dos valores no idioma padrão.

Criar Chaves de Pacotes de Recursos

As chaves de pacotes de recursos são usadas para identificar texto de saída que precisa ser traduzido e fornecer valores em um ou mais idiomas. As chaves são definidas automaticamente para os nomes das conversas de intenção, as respostas das intenções de resposta e algumas propriedades comuns. No entanto, você mesmo precisa criar chaves para outro texto de saída que queira traduzir, como texto do fluxo de caixas de diálogo.

Para criar entradas de pacotes de recursos:

Na barra de navegação esquerda da habilidade, clique em .
Clique na guia Definido pelo Usuário.
Clique em Adicionar Pacote.

A caixa de diálogo Criar Entrada é exibida, o que permite criar sua primeira entrada no idioma principal da habilidade.
Digite a chave (que você usa para fazer referência à entrada do pacote) e seu texto correspondente. Por exemplo, para o prompt do usuário How old you?, você pode digitar HowOld no campo Chave e, em seguida, How old you? no campo Texto.
Para Anotação, digite quaisquer informações que serão úteis para aqueles que talvez precisem referenciar a entrada posteriormente, como tradutores.
Clique em Criar Entrada.

Adicionar um Idioma a uma Chave de Pacote de Recursos

Quando você cria uma chave de pacote, o valor inicial Texto é para o padrão da habilidade (ou seja o idioma principal ou predominante).

Para adicionar texto para uma chave de pacote em outro idioma:

Selecione a chave e clique em Adicionar Idioma.
Preencha a caixa de diálogo Criar Entrada:
- Idioma - Informe ou selecione uma tag de idioma IETF BCP 47 como fr para francês ou de para alemão.
- Texto — A string de saída. Por exemplo, para uma tradução em francês (fr) da chave HowOld, você adicionaria uma string como quel âge avez-vous?

Observação

Você também pode usar configurações regionais mais específicas (como en-US), mas elas não são úteis na maioria dos casos. Por exemplo, se você estiver usando um serviço de tradução para detectar o idioma, somente um código de duas letras será retornado.

Se a habilidade não puder corresponder ao idioma de entrada com uma tag de idioma definida no pacote, ela assumirá como padrão uma tag menos específica (se houver uma disponível). Se nenhuma das entradas corresponder ao idioma do browser, a habilidade usará a entrada padrão, Inglês. Consulte Resolução de Entrada do Pacote de Recursos para obter detalhes.

Traduzir o Nome da Conversa

Em alguns pontos dentro de uma conversa, como quando a habilidade está tentando determinar qual fluxo o usuário deseja seguir, a habilidade pode apresentar uma caixa de diálogo que se refere a mais intenções. Nesses casos, a habilidade se refere às intenções por seus nomes de conversas, cujas chaves e entradas padrão são geradas no pacote de recursos.

Para fornecer uma tradução para um nome de conversa:

Clique em Pacote de Recursos na barra de navegação esquerda ().
Clique na guia Intenções na página Pacotes de Recursos.

Descrição da ilustração rb-conversation-name.png
Selecione a intenção
Clique em Adicionar Idioma.
Preencha a caixa de diálogo Criar Entrada:
- Idioma — Adicione uma tag de idioma IETF BCP 47 como fr para francês, de para alemão ou en-US para inglês americano.
- Texto — A string de saída. Por exemplo, para uma tradução em francês (fr) da chave HowOld, você adicionaria uma string como quel âge avez-vous?

Observação

Se a intenção cujo nome da conversa você deseja alterar não aparecer na lista, clique em

para voltar à página Intenções, selecione a intenção e edite o campo Nome da Conversa. Quando você retornar à página Pacotes de Recursos, ela deverá aparecer na guia Intenções.

Traduzir Respostas para Intenções de Resposta

Quando você cria uma intenção de resposta, uma chave de pacote de recursos é criada automaticamente para a resposta.

Para fornecer uma tradução para uma resposta em uma intenção de resposta:

Clique em Pacote de Recursos na barra de navegação esquerda ().
Clique na guia Perguntas e Respostas na página Pacotes de Recursos.
Selecione a chave da resposta que deseja traduzir.
Clique em Adicionar Idioma.
Preencha a caixa de diálogo Criar Entrada:
- Idioma — Adicione uma tag de idioma IETF BCP 47 como fr para francês, de para alemão ou en-US para inglês americano.
- Texto — A string de saída.

Mencionar Pacotes de Recursos no Fluxo de Caixas de Diálogo

Para definir a saída de um componente incorporado, você menciona a chave da mensagem por meio da variável rb (que é reservada para pacotes de recursos).

Aqui está uma expressão simples que faz referência a uma chave de pacote chamada WhatType para retornar uma string simples:

${rb('WhatType')}

Aqui está uma expressão que usa valores dinâmicos. Ele faz referência a uma chave de pacote chamada OnTheWay, na qual size.value e type.value são os argumentos da chave OnTheWay.


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

Também é possível criar entradas de pacotes com formatos de mensagem mais complexos para identificar plurais e outros casos. Consulte os tópicos a seguir para saber mais sobre a faixa de formatos de mensagem e como mencioná-los em seu fluxo de caixas de diálogo.

Dica:

Para testar pacotes de recursos usando o testador, defina o browser com outro idioma.

Formatos de Mensagem

Existem vários formatos que você pode usar em suas mensagens de pacotes de recursos para tratar tudo, desde retornar mensagens estáticas até montar mensagens, dependendo de diversas variáveis.

Mensagens Simples

Para mensagens estáticas simples:

Como valor da chave de pacote, forneça texto sem formatação. Por exemplo: This is the value of my bundle key
No fluxo de caixas de diálogo ou na propriedade de configuração, mencione a chave de pacote no formato: {rb.bundleKey} ou {rb('bundleKey')}

Exemplo: Mensagem Simples

Veja um exemplo sem parâmetros.

Chave de Pacote de Recursos: pizzaOnTheWay
Mensagem de Pacote de Recursos: Your pizza is on the way.
Expressão para Referenciar Chave de Pacote de Recursos: ${rb('pizzaOnTheWay')} (ou ${rb.pizzaOnTheWay})

Mensagens com Parâmetros

Para mensagens com variáveis:

Como valor da chave de pacote, forneça texto e inclua parâmetros em um dos seguintes formatos:
- Parâmetros nomeados no formato {parameterName}
- Parâmetros sequencialmente numerados começando com {0}
No fluxo de caixas de diálogo ou na propriedade de configuração, mencione a chave de pacote no formato:
```
${rb('bundleKey','variable1','variable2',...)}
```

Exemplo: Mensagem com Parâmetros Nomeados

Veja um exemplo com dois parâmetros nomeados:

Chave de Pacote de Recursos: pizzaOnTheWayWithNamedParams
Mensagem do Pacote de Recursos (em inglês):
```
Your {pizzaSizeParam} {pizzaTypeParam} pizza is on the way.
```
(em que {pizzaSizeParam} e {pizzaTypeParam} são parâmetros de valores a serem resolvidos e inseridos durante a conversa)
Expressão para Referenciar Chave de Pacote de Recursos:
```
${rb('pizzaOnTheWayWithNamedParams','pizzaSizeParam,pizzaTypeParam',pizzaSize.value,
      pizzaType.value)}
```
(em que pizzaSize e pizzaType são variáveis definidas no fluxo de caixas de diálogo)

Exemplo: Mensagem com Parâmetros Numerados

Veja um exemplo de como usar parâmetros numerados:

Chave de Pacote de Recursos: pizzaOnTheWayWithNumberedParams
Mensagem do Pacote de Recursos:
```
Your {0} {1} pizza is on the way.
```
(em que {0} e {1} são parâmetros de valores a serem resolvidos e inseridos durante a conversa)
Expressão para Referenciar Chave de Pacote de Recursos:
```
${rb('pizzaOnTheWayWithNumberedParams',pizzaSize.value, pizzaType.value)}
```
(em que pizzaSize e pizzaType são variáveis definidas no fluxo de caixas de diálogo)

Mensagens Complexas

Também é possível criar mensagens complexas, em que o valor de uma ou mais variáveis pode afetar o texto de saída adjacente. Por exemplo, se a resposta incluir uma variável para o número de pizzas solicitadas, você poderá usar uma mensagem complexa para determinar se deve ser usado singular ("pizza") ou plural ("pizzas").

Dica:

Ao compor entradas de pacotes complexas, você pode usar esse testador para garantir que as entradas sejam resolvidas da forma planejada:https://format-message.github.io/icu-message-format-for-translators/editor.html.

Mensagens que Identificam Singular e Plural

Para mensagens que incluem uma variável que expressa a quantidade de algo, pode ser necessário variar a redação da mensagem montada, dependendo de como a variável é resolvida. E, para alguns idiomas, pode ser necessário considerar mais que uma simples distinção de singular/plural. Para identificar mensagens com variáveis de quantidade, você pode usar um argumento plural no valor da chave para especificar as diferentes maneiras que a mensagem pode precisar ser construída.

Em um argumento plural, parte da mensagem é determinada por um valor numérico com regras gramaticais do idioma especificado. Você define o texto da mensagem para diferentes casos, dependendo de como o argumento plural é resolvido. Há vários casos predefinidos, como one, two, few, many e other. Você também pode especificar um caso para um número específico, anexando = a esse número (por exemplo, =3). Nem todos os casos predefinidos são relevantes para cada idioma. Por exemplo, no inglês, você pode apenas usar =0, =1 e other.

Sempre inclua um caso e uma mensagem para other. Para incluir o número resolvido no texto da mensagem de um caso, use # para gerar o número.

Quando você usa argumentos plural, o formato geralmente se parece com o este:

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

No exemplo anterior, 0, 1 e other são as quantidades possíveis. Mais detalhes sobre como os tipos de argumento plural funcionam podem ser encontrados na especificação de Marcação de Dados de Configuração Regional Unicode.

Para obter detalhes sobre o suporte a plural para vários idiomas, consulte as regras de idioma plural unicode.org.

Outras Mensagens Complexas

Se o conteúdo da mensagem precisar se basear em outras condições, você poderá usar um argumento select com palavras-chave que definir para montar a mensagem.

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

Você também pode aninhar plural e selecionar argumentos:

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

Observação

Para nomes de palavra-chave, só use caracteres alfabéticos ASCII (A-Z,a-z).

Você pode encontrar mais detalhes sobre mensagens complexas em https://unicode-org.github.io/icu/userguide/format_parse/messages/#complex-argument-types.

fazendo referência a mensagens complexas

Você pode fazer referência a mensagens de pacotes de recursos complexos das duas seguintes maneiras:

Usando uma variável de mapa em que os valores de cada um dos parâmetros são montados:
```
${rb('bundleKey', formatMap.value)}
```
Incluindo um argumento de lista com os nomes dos parâmetros seguidos por argumentos de cada valor:
```
${rb('bundleKey', 'param1, param2, param3', paramValue1, paramValue2, paramValue3)}
```
Observação

Onde os valores dos parâmetros são strings, eles deverão estar entre aspas simples (').

Para obter mais detalhes, consulte o tópico Tipos de Argumentos Complexos na documentação do ICU.

Mapas para Valores de Pacotes de Recursos Complexos

Se você decidir usar a variável de mapa para montar os parâmetros de uma mensagem complexa, é isto que fará:

Defina uma variável do tipo mapa e dê a ela um valor no formato JSON válido. Por exemplo, o valor de uma entrada de pacote de pizza pode ser semelhante a:
```
{
    "pizzaSize": "${pizzaSize.value}",
    "pizzaType:": "${pizzaType.value}",
    "count": "${pizzaNum.value}"
}
```
Observação

Em fluxos de caixas de diálogo baseados em YAML, primeiro você declara a variável dentro do nó context e, em seguida, usa um componente System.SetVariable para definir seu valor com sintaxe como a seguinte:
```
  populateMap:
    component: "System.SetVariable"
    properties:
      variable: "formatMap"
      value:
        pizzaSize: "${pizzaSize.value}"
        pizzaType: "${pizzaType.value}"
        count: "${pizzaNum.value}"
```
Na expressão em que você faz referência à chave de pacote, inclua o mapa como argumento. Por exemplo :
```
${rb('pizzaOnTheWaySingularOrPlural', formatMap.value)}
```

Exemplo: Mensagem que Identifica Variantes de Singular e Plural

Veja um exemplo de entrada de pacote de recursos para uma mensagem que pode ter conteúdo singular ou plural:

Chave de Pacote de Recursos: pizzaOnTheWaySingularOrPlural

Mensagem do Pacote de Recursos (em 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.}
}

Expressão para Referenciar Chave de Pacote de Recursos:
```
${rb('pizzaOnTheWaySingularOrPlural','count, pizzaSizeParam, pizzaTypeParam', 'pizzaNum.value, pizzaSize.value, pizzaType.value')}
```
Como você pode ver, a expressão contém dois argumentos:
- Uma lista de nomes de parâmetros (count, pizzaSizeParam, pizzaTypeParam)
- Uma lista de valores para esses parâmetros (pizzaNum.value, pizzaSize.value, pizzaType.value)

Exemplo: Mensagem com Parâmetros Aninhados

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

Veja aqui as variações de como essa mensagem pode ser resolvida:

Ela não pediu nada.
Ela pediu apenas uma.
Ela pediu 2.
Ele não pediu nada.
Ele pediu apenas uma.
Ele pediu 2.
Eles não pediram nada.
Eles pediram apenas uma.
Eles pediram 2.

Observação

2 é fornecido no exemplo anterior como número resolvido pelo argumento count, mas pode ser qualquer número diferente de 0 ou 1.

Pacotes de Recursos e Tradução Automática de Habilidades

Veja as etapas gerais para configurar uma habilidade para usar um serviço de tradução apenas para entrada do usuário, enquanto utiliza pacotes de recursos para as respostas da habilidade:

Se você não tiver feito isso ainda, adicione um serviço de tradução à sua habilidade.
Use o componente Detectar Idioma para determinar o idioma da entrada do usuário.
Aplique pacotes de recursos para tratar as respostas da habilidade ao usuário.
Para qualquer componente que faça referência a pacotes de recursos, certifique-se de que a saída não seja traduzida automaticamente.
- Para habilidades desenvolvidas no modo de caixa de diálogo Visual, defina a propriedade Traduzir Mensagem de Resposta do Bot na página Definições da habilidade como False.
- Para habilidades desenvolvidas no modo de caixa de diálogo YAML, você pode tratar isso globalmente na habilidade definindo a variável de contexto autoTranslate para traduzir entrada e não traduzir saída. Por exemplo :
```
  setAutoTranslate:
    component: "System.SetVariable"   
    properties:
      variable: "autoTranslate"     
      value:
       input: true
       output: false
```

Observação

Para habilidades desenvolvidas no modo YAML, você também pode identificar isso no nível do componente usando a propriedade translate de cada componente e não definindo a variável autoTranslate. Por exemplo, para configurar a tradução automática para uma entrada do componente System.Text e desativar a tradução automática para saída, você pode fazer o seguinte:

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

Se sua habilidade usar pacotes de recursos para alguns componentes, mas depender de tradução automática para outros componentes, você poderá fazer o seguinte:

Defina a variável de contexto autoTranslate como true.
Como na amostra de código anterior, defina a propriedade translate:input como false para cada componente que usa um pacote de recursos.

Tradução Automática Condicional

Se você tiver definido pacotes de recursos para alguns idiomas, mas também quiser fornecer respostas para idiomas para os quais você não tem entradas de pacotes de recursos, poderá usar expressões FreeMarker para determinar como resolvem as definições Traduzir Mensagem de Entrada do Usuário e Traduzir Mensagem de Resposta do Bot (para habilidades do Visual Flow Designer) e as propriedades autotranslate e translate (para habilidades baseadas em YAML).

Por exemplo, se apenas os pacotes de recursos inglês e holandês estiverem definidos, você poderá ativar condicionalmente a tradução da saída para os outros idiomas. Veja como essa expressão pode se parecer:

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

Resolução de Entrada do Pacote de Recursos

O pacote de recursos aplicado depende do valor armazenado para as duas variáveis de perfil de usuário específicas da localidade, profile.languageTag e profile.locale. Se ambas as variáveis forem definidas, profile.languageTag terá precedência.

Ao resolver qual idioma usar, o Oracle Digital Assistant primeiro procura uma correspondência exata. Se nenhuma for encontrada, ele ampliará incrementalmente a pesquisa até obter sucesso. Se ainda assim não conseguir encontrar uma correspondência, ela retornará o idioma padrão, que é o inglês (en).

Por exemplo, se o valor de ${profile.locale} for en-AU-sydney (e profile.languageTag não estiver definido), o Oracle Digital Assistant fará o seguinte para encontrar a melhor correspondência de idioma:

Pesquisa o pacote pelos critérios idioma-país-variante (en-AU-sydney).
Se não conseguir encontrar, ele vai procurar o pacote por idioma e país (en-AU).
Se não tiver sucesso, ele ampliará a procura do idioma (en).

Observação

O profile.locale suporta valores nos formatos de idioma ISO - país ou ISO language_country.

Exportar e Importar Pacotes de Recursos

Você pode exportar e importar pacotes de recursos na forma de um arquivo CSV, o que permite trabalhar com os pacotes off-line.

O arquivo CSV precisa ter as seguintes colunas:

languageTag
key
message
annotation

Para exportar um arquivo CSV com o pacote de recursos existente:

Na página Pacote de Recursos da habilidade ou do assistente digital, clique em para exportar um arquivo CSV com o pacote de recursos existente.

Mesmo que você ainda não tenha adicionado chaves ao pacote de recursos, um arquivo com o formato necessário do CSV será exportado.

Para importar um arquivo de pacote de recursos:

Na página Pacote de Recursos da habilidade ou do assistente digital, clique em .

Documentação do Oracle Cloud Infrastructure