Configurar e criar agentes multilíngues

Ao utilizar o Copilot Studio, pode criar um agente que comunica com os clientes em vários idiomas. Pode configurar agentes multilingues para detetar automaticamente o idioma pretendido com base nas definições do browser web do utilizador do agente e responder nesse mesmo idioma, oferecendo uma experiência mais personalizada e envolvente aos clientes.

Quando cria um agente, especifica o seu idioma principal.

Depois de adicionar idiomas secundários a um agente, é responsável por fornecer as traduções das mensagens nos tópicos que cria. Para agentes que utilizam orquestração generativa, as mensagens geradas são traduzidas automaticamente.

Quando um cliente inicia uma sessão com um agente publicado, o agente seleciona um dos seus idiomas para corresponder ao idioma definido no cliente ou browser do utilizador. Se o agente não conseguir detetar o idioma ou detetar um idioma que não é suportado, o agente utiliza o seu idioma principal.

Pode configurar um agente para alterar o idioma que utiliza durante uma conversa (consulte Fazer com que um agente mude para outro idioma). Também pode configurar um agente que utilize orquestração generativa para alternar dinamicamente entre idiomas, seguindo o idioma utilizado na conversa atual (consulte Configurar um agente para alternância dinâmica entre idiomas).

Para a lista de idiomas suportados, consulte Suporte a idiomas.

Nota

Os chatbots clássicos suportam apenas um idioma. Para mais informações sobre como converter um chatbot clássico num agente, consulte Atualizar para criação unificada do Copilot Studio.

Adicionar idiomas a um agente

1. Aceda à página Definições do agente e selecione Idiomas.

2. Selecione Adicionar idioma.

3. No painel Adicionar idiomas, selecione os idiomas que pretende adicionar ao agente e selecione Adicionar.

4. Reveja a lista de idiomas e feche a página Definições.

Gerir a localização para um agente multilingue

No Copilot Studio, realiza toda a edição de tópicos e conteúdos no idioma principal do agente. Esta secção explica como transferir cadeias de carateres do seu agente e traduzi-las para os idiomas secundários do seu agente. Depois de carregar as cadeias de carateres traduzidas, pode alterar o idioma no painel de teste e verificar se as conversas nos idiomas secundários também fluem conforme esperado.

Preparar conteúdo localizado

Quando transfere o ficheiro de localização para um idioma secundário pela primeira vez, todas as cadeias de carateress estão no idioma principal do agente. Depois de transferir o ficheiro de localização, utilize-o com o seu processo de localização preferido.

1. Aceda à página Definições do seu agente e selecione Idiomas.

2. Na página Idiomas, na lista de idiomas secundários, selecione Carregar para o idioma que pretende atualizar.

3. No painel Atualizar localizações, selecione o formato JSON ou ResX para transferir o ficheiro de localização atual para esse idioma.

   Nota

   O ficheiro transferido contém o conteúdo de localização mais recente do agente. Para transferir versões anteriores do ficheiro de localização, abra a solução do agente.

4. Abra o ficheiro transferido e substitua as cadeias de carateres do idioma principal pelo texto traduzido apropriado.

5. Volte ao painel Atualizar localizações, selecione Procurar e carregue o ficheiro traduzido.

6. Feche o painel Atualizar localizações e a página Definições.

Atualizar conteúdo localizado

Se alterar as cadeias de texto do idioma principal, terá também de atualizar o conteúdo nos idiomas secundários. Este processo inclui tanto conteúdo novo como conteúdo modificado. As alterações incrementais não são traduzidas automaticamente. Deve transferir o ficheiro JSON ou ResX do idioma secundário e atualizar as cadeias de carateres não traduzidas usando o seu processo de localização preferido.

O seguinte cenário é típico do fluxo de trabalho para conteúdo traduzido. Anteriormente traduziu o seu idioma principal (en-US) para um idioma secundário (fr-FR), e adicionou e modificou conteúdo no idioma principal. Quando transfere o ficheiro de localização para o idioma secundário, quaisquer novas cadeias de carateres estão no idioma principal (en-US) e as cadeias de carateres que já foram traduzidas permanecem no idioma secundário (fr-FR). No entanto, as cadeias de carateres previamente traduzidas cujo texto original foi modificado desde a última vez que carregou o ficheiro de localização continuam a aparecer tal como foram traduzidas para o idioma secundário. Como os IDs das cadeias de carateres não mudam, as cadeias de carateres do idioma secundário e do idioma principal podem ficar fora de sincronização após alterações no idioma principal. Inclua a comparação do novo ficheiro de localização com a versão que carregou anteriormente, para identificar alterações nas cadeia de carateress no idioma principal, como parte do seu processo de localização.

Criar conteúdo dinâmico a partir dos Cartões Adaptativos para localização

Os ficheiros de localização não incluem cadeias de carateres de tipo misto de Cartões Adaptativos. Se precisar de localizar um Cartão Adaptativo em que uma cadeia de carateres de texto possa incluir tanto texto estático como variáveis (conteúdo dinâmico), utilize o seguinte método alternativo. O procedimento mostra como utilizar um nó Definir variável de texto para armazenar a cadeia de carateres completa com o texto estático e as variáveis numa variável intermédia. Depois, consulte apenas essa variável intermédia no seu Cartão Adaptativo. Quando transferir um ficheiro de localização para o seu agente, o valor da variável intermédia, com o texto estático e as referências das variáveis, estará disponível para localização como parte de uma ação setVariable.

Para tornar o conteúdo dinâmico de um Cartão Adaptativo localizável:

1. Adicione um nó Definir valor variável antes do seu Cartão Adaptativo. Este passo cria uma representação YAML que pode ser atualizada utilizando o editor de código para converter o nó num nó Definir variável de texto. Não é possível criar nós Definir variável de texto diretamente da tela de criação.

2. No nó Definir valor da variável, crie uma nova variável mas ainda não defina o valor.

3. Abra o editor de código para o seu tópico.

4. No editor de código, localize a parte que representa o nó Definir o valor da variável e substitua kind: SetVariable por kind: SetTextVariable. Esta alteração converte o nó Definir valor da variável num nó de Definir variável de texto.

5. Feche o editor de código.

6. Selecione o campo inferior do nó Definir variável de texto e introduza a cadeia de carateres completa com o texto estático e as variáveis que quer mostrar no seu Cartão Adaptativo. Insira uma variável da mesma forma que insere uma variável numa mensagem.

7. Atualize o Cartão Adaptativo com uma referência a esta nova variável.

8. Guarde o seu tópico. Agora pode transferir o ficheiro de localização e verificar que inclui o conteúdo dinâmico dos seus Cartões Adaptativos.

Saiba mais em Localizar conteúdos do Cartão Adaptativo.

Testar um agente multilingue

1. Abra o painel de teste.

2. Selecione os três pontos (…) no topo do painel de teste e selecione o idioma que pretende. O painel de teste recarrega-se, desta vez no idioma selecionado. A tela de criação permanece no idioma principal e não pode guardar as alterações que fizer a um tópico até voltar a mudar para o idioma principal.

3. Para testar o agente, introduza uma mensagem no idioma selecionado.

Também pode definir o idioma do seu browser para um dos idiomas do seu agente e aceder ao site de demonstração pré-criado. O site de demonstração abre no idioma especificado e o agente conversa nesse mesmo idioma.

Fazer um agente mudar de idioma

Ao criar, pode configurar o agente para mudar para outro idioma a meio de uma conversa. A lógica pode residir em qualquer tópico do agente. No entanto, a melhor prática é alterar o idioma logo após um nó de Pergunta, o que garante que todas as mensagens seguintes até ao próximo nó de Pergunta estejam no mesmo idioma.

Para alterar o idioma atual do agente, defina a User.Languagevariável do sistema para um dos idiomas secundários do seu agente. Esta seleção altera imediatamente o idioma utilizado pelo seu agente.

Configurar um agente para alternância dinâmica de idiomas

Nota

Esta funcionalidade está disponível apenas para agentes com orquestração generativa ativada.

Pode configurar um agente para detetar o idioma que um cliente utiliza e responder nesse mesmo idioma. Com esta configuração, o agente pode alternar entre idiomas várias vezes ao longo de uma única conversa. O cenário seguinte mostra como configurar um agente para alternar entre holandês e inglês. Pode expandi-lo para qualquer combinação de idiomas suportados pelo seu agente.

Aviso

Este método dinâmico de mudança de idioma não é compatível com a deteção de idioma baseada no browser. Uma vez que o tópico que deteta dinamicamente o idioma do utilizador define a variável User.Language, a deteção de idioma baseada no browser deixa de ter efeito para esse utilizador, mesmo que o tópico seja posteriormente desativado ou eliminado. Se pretende experimentar ou validar ambas as abordagens, utilize um agente de teste separado. Depois de testar a alternância dinâmica de idiomas, deve limpar o estado persistente do idioma do utilizador antes de tentar testar a deteção de idioma baseada no browser.

Este cenário usa um tópico com um acionador do tópicoMensagem recebida. Este acionador de tópico permite que o seu agente examine todas as mensagens que recebe. Este tópico utiliza um pedido personalizado para detetar o idioma e uma condição para definir a variável de sistema do idioma do agente.

1. Verifique se o seu agente está configurado para suportar todos os idiomas que pretende.

2. Criar um tópico.

3. Substitua o tipo de acionador predefinido para o tópico por Mensagem recebida.

4. Adicione um pedido ao seu tópico:

   1. Selecione o ícone Adicionar nó abaixo do nó Acionador.

   2. Selecione Adicionar uma ferramenta>Novo pedido.

   3. No editor de pedidos, introduza um nome representante para o seu pedido, como "Detetar idioma."

   4. No painel Instruções, introduza "Determine em que idioma está escrita esta mensagem:".

   5. No fundo do painel de Instruções, selecione Adicionar conteúdo e selecione Texto. Abre-se uma janela onde deve inserir um nome e uma mensagem de amostra.

   6. No Nome, introduza "Mensagem". Nos Dados de amostra, introduza "Mensagem do utilizador" e selecione Fechar.

   7. No painel Resposta do modelo, altere o formato de Saída para JSON.

   8. Selecione Teste. O seu pedido mostra um literal JSON, com uma única propriedade identificando o idioma como inglês.

      

   9. Selecione Guardar. Um nó Pedido aparece no painel.

5. Configure o nó Pedido :

   1. Para Entrada, selecione a variável do sistemaActivity.Text (o texto da mensagem recebida).
   2. Para Saída, crie uma nova variável chamada DetectedLanguage...

6. Ramifique a lógica com base no idioma detetado:

   1. Adicione uma condição abaixo do nó Pedido.

   2. Baseie a sua condição na variável personalizada « DetectedLanguage.structuredOutput.language, que contém o nome do idioma detetado.

   3. Adicione um ramo de condição para cada idioma que necessita de detetar.

   4. Em cada ramo, adicione um nó Definir valor de variável para definir a variável de sistema User.Language em conformidade. A imagem seguinte mostra um tópico com uma condição para alternar entre holandês e inglês.

      

Restaurar a deteção de idioma baseada no browser

Quando um agente configurado para mudança dinâmica de idioma define a variável de sistema User.Language, o idioma selecionado mantém-se como uma substituição para o utilizador do agente. O idioma preferido do utilizador é determinado pela seguinte ordem de prioridades:

1. Preferência de idioma definida explicitamente pelo utilizador e mantida como substituição para este utilizador (prioridade mais elevada).
2. Mensagem recebida do utilizador num idioma que corresponde a um dos idiomas suportados pelo agente (Activity.Locale).
3. O idioma principal do agente (base).

Para limpar o idioma persistente após testar a alternância dinâmica de idiomas:

• Envie /debug clearstate para o agente. Este comando limpa a substituição de idioma do estado do utilizador.

Resolução de problemas de um agente multilingue

Esta secção apresenta sugestões que ajudam a compreender o comportamento inesperado de um agente multilingue.

Comportamento do agente multilingue para idiomas não configurados

Se um utilizador configurar o browser com um idioma que não configurou para o agente, o agente volta ao seu idioma principal.

Especifique o idioma principal de um agente quando cria um agente. Não é possível mudar o idioma principal após a criação, mas pode alterar a região do idioma principal do agente, se houver mais do que uma região disponível.

Comportamento do agente multilingue para traduções em falta

Se adicionar mensagens a um agente no seu idioma principal mas não carregar as traduções dessas novas mensagens, o agente mostra as novas mensagens não traduzidas no seu idioma principal. Certifique-se sempre de que as traduções estão atualizadas após fazer alterações num agente.

Os ficheiros de localização não incluem cadeias de carateres de tipo misto de Cartões Adaptativos. Se precisar de localizar Cartões Adaptativos onde uma cadeia de carateres pode incluir tanto texto estático como variáveis (conteúdo dinâmico), deve usar uma solução alternativa. Aprenda a armazenar uma cadeia de caracteres mistos numa variável de texto antes de a usar nos Cartões Adaptativos.

Erros ao publicar um agente multilingue

Quando tenta publicar um agente multilingue, poderá ver a mensagem de erro "A validação do bot falhou", com o código de erro de resposta não processada SynonymsNotUnique. Este erro significa que o seu ficheiro de localização contém sinónimos duplicados ou um sinónimo que coincide com o valor DisplayName. Normalmente encontra este erro quando um nó contém um Entity.Definition.'closedListItem' onde ocorreu um dos seguintes cenários:

• Um dos elementos Synonyms não é único.
• Um dos elementos Synonyms tem o mesmo valor que o elemento DisplayName.

Todos os Synonyms para a mesma entidade têm de ser exclusivos e ter um nome diferente do elemento DisplayName.

Para corrigir o erro, reveja o ficheiro JSON ou ResX do seu idioma secundário e identifique quaisquer casos em que esta condição possa estar presente.