Configurar e criar agentes multilingues

Os agentes multilíngues se comunicam com os clientes em diferentes idiomas, mantendo todo o conteúdo em um único agente. Em muitos casos, eles detetam automaticamente o idioma desejado com base na configuração do navegador da Web do usuário agente e respondem no mesmo idioma, proporcionando uma experiência mais personalizada e envolvente para os clientes.

Ao criar um agente, você especifica seu idioma principal.

Depois de adicionar idiomas secundários a um agente, você é responsável por fornecer as traduções para mensagens em tópicos criados. Para agentes que usam 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 de seus idiomas para corresponder ao idioma especificado no cliente ou navegador do cliente. Se o agente não conseguir detetar o idioma do cliente ou do navegador, ou se o idioma detetado não for um dos idiomas especificados para o agente, o agente assumirá como padrão o idioma principal.

Você pode projetar um agente para alterar o idioma que ele usa durante uma conversa (consulte Fazer um agente mudar para outro idioma). Você também pode configurar um agente que usa orquestração generativa para alternar dinamicamente idiomas para seguir o idioma usado no turno de conversação atual (consulte Configurar um agente para troca dinâmica de idioma).

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

Adicionar idiomas a um agente

1. Vá para a página Configurações do agente e selecione Idiomas.

2. Selecione Adicionar idiomas.

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

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

Gerenciar a localização de um agente multilíngue

No Copilot Studio, você executa toda a edição de tópicos e conteúdo 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 caracteres traduzidas, você pode alternar o idioma no painel de teste e verificar se as conversas nos idiomas secundários também fluem conforme o esperado.

Preparar conteúdo localizado

Quando você baixa pela primeira vez o arquivo de localização para um idioma secundário, todas as cadeias de caracteres estão no idioma principal do agente. Depois de baixar um arquivo de localização, use-o com seu processo de localização preferido.

1. Vá para a página Configurações do seu agente e selecione Idiomas.

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

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

   Observação

   O arquivo baixado contém o conteúdo de localização mais recente para o agente. Se você precisar baixar versões anteriores do arquivo de localização, abra a solução do agente.

4. Abra o arquivo baixado e substitua as cadeias de caracteres do idioma principal pelo texto traduzido apropriado.

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

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

Atualizar conteúdo localizado

Se você fizer alterações nas cadeias de caracteres do idioma principal, também deverá atualizar o conteúdo nos idiomas secundários. Este processo inclui conteúdo novo e conteúdo modificado. As alterações incrementais não são traduzidas automaticamente. Você deve baixar o arquivo JSON ou ResX no idioma secundário e atualizar as cadeias de caracteres não traduzidas usando seu processo de localização preferido.

O cenário a seguir é típico do fluxo de trabalho para conteúdo traduzido. Você traduziu anteriormente seu idioma principal (en-US) para um idioma secundário (fr-FR) e adicionou e modificou conteúdo no idioma principal. Quando você baixa o arquivo de localização para o idioma secundário, todo o novo conteúdo está no idioma principal (en-US). No entanto, o conteúdo modificado ainda aparece no idioma secundário. Como o conteúdo modificado usa a mesma ID, você deve comparar o novo arquivo com o arquivo carregado anteriormente.

Disponibilizar conteúdo dinâmico de Cartões Adaptáveis para localização

Os arquivos de localização não incluem strings de tipo misto de Adaptive Cards. Se você precisar localizar um Adaptive Card onde uma cadeia de caracteres pode incluir texto estático e variáveis (conteúdo dinâmico), use a seguinte solução alternativa. 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. Em seguida, você faz referência apenas a essa variável intermediária no seu Adaptive Card. Quando você baixa um arquivo de localização para seu agente, o valor de sua variável intermediária, com o texto estático e as referências de variáveis, fica disponível para localização como parte de uma setVariable ação.

Para tornar o conteúdo dinâmico de um Adaptive Card 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. Essa alteração converte o nó Definir valor da variável em um nó Definir variável de texto.

5. Feche o editor de códigos.

6. Selecione o campo inferior do nó Definir variável de texto e insira a cadeia de caracteres completa com o texto estático e as variáveis que você deseja mostrar no seu Adaptive Card. Insira uma variável da mesma forma que você inseriria uma variável em uma mensagem.

7. Atualize o seu Adaptive Card com uma referência a esta nova variável.

8. Salve seu tópico. Agora você pode baixar o arquivo de localização e verificar se ele inclui o conteúdo dinâmico para seus Adaptive Cards.

Realizar teste de um agente multilingue

1. Abra o painel de teste.

2. Selecione os três pontos (...) no topo do painel de teste e selecione a língua que deseja. O painel de teste recarrega-se, desta vez usando o idioma selecionado. A tela de criação permanece no idioma principal e você não pode salvar as alterações feitas em um tópico até voltar para o idioma principal.

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

Você também pode definir o idioma do navegador para um dos idiomas do seu agente e ir para o site de demonstração pré-construído. O site de demonstração é aberto no idioma especificado e o agente conversa nesse idioma.

Fazer um agente mudar para outro idioma

Ao redigir, pode configurar o agente para alternar para outro idioma no meio de uma conversa. A lógica pode residir em qualquer tópico no agente. No entanto, a prática recomendada é mudar de idioma imediatamente após um nó Pergunta, o que garante que todas as mensagens a seguir até o próximo nó Pergunta sejam no mesmo idioma.

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

Configurar um agente para comutação dinâmica de idioma

Você pode configurar um agente para detetar o idioma que um cliente usa e responder no mesmo idioma. Com essa configuração, o agente pode alternar de idioma várias vezes ao longo de uma única conversa. O cenário a seguir mostra como configurar um agente para alternar entre holandês e inglês. Você pode estendê-lo para qualquer combinação dos idiomas suportados pelo seu agente.

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

1. Crie um tópico.

2. Substitua o tipo de gatilho padrão para o tópico por Uma mensagem é recebida.

3. Adicione um prompt ao seu tópico:

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

   2. Selecione Adicionar uma ferramenta>Novo prompt.

   3. No editor de prompts, insira um nome de representante para o prompt, como "Detetar idioma".

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

   5. Na parte inferior do painel Instruções , selecione Adicionar conteúdo e selecione Texto. Uma janela é exibida convidando você a inserir um nome e uma mensagem de exemplo.

   6. Em Nome, digite "Mensagem". Em Dados de exemplo, digite "Mensagem do usuário" e selecione Fechar.

   7. No painel de resposta do modelo, alterne 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.

4. Configure o nó Pedido :

   1. Em Input, selecione a variávelActivity.Text de sistema (o texto da mensagem recebida).
   2. Para Output, crie uma nova variável chamada DetectedLanguage.

5. Ramifique sua lógica com base no idioma detetado:

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

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

   3. Adicione uma ramificação de condição para cada idioma que você precisa 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 a seguir mostra um tópico com uma condição para alternar entre holandês e inglês.

      

Solucionar problemas de um agente multilíngue

Esta seção fornece dicas para entender o comportamento inesperado do agente multilíngue.

Comportamento do agente multilíngue para idiomas que não estão configurados

Se um usuário configurar seu navegador para um idioma que você não configurou para o agente, o agente voltará ao seu idioma principal.

Você especifica o idioma principal para um agente ao criar o agente. Não é possível alterar o idioma principal após a criação, mas é possível alterar a região do idioma principal do agente, se houver mais de uma região disponível.

Comportamento de agente multilíngue perante traduções em falta

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

Os arquivos de localização não incluem strings de tipo misto de Adaptive Cards. Se você precisar localizar Adaptive Cards onde uma cadeia de caracteres pode incluir texto estático e variáveis (conteúdo dinâmico), deverá usar uma solução alternativa. Saiba como armazenar uma cadeia de caracteres de tipo misto em uma variável de texto antes de usá-la em um Adaptive Card.

Erros ao publicar um agente multilíngue

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

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

Todos Synonyms para a mesma entidade devem ser exclusivos e ter um nome diferente do DisplayName elemento .

Para corrigir o erro, revise o arquivo JSON ou ResX para seu idioma secundário e identifique quaisquer instâncias em que essa condição possa estar presente.