## Visão geral

A tradução automática permite que uma equipe trabalhe com clientes de outros países sem perder o
contexto original da conversa. O Conversa Labs separa três decisões que não devem ser confundidas:

- **Meu idioma para traduções**: idioma em que cada agente visualiza mensagens e transcrições.
- **Idioma padrão da equipe**: fallback compartilhado definido no Inbox ou na conversa.
- **Idioma de entrega ao contato**: idioma em que a resposta realmente sai pelo canal.

Assim, um atendente pode escrever e ler em português, o contato receber em inglês e outro agente da
mesma equipe visualizar a mesma conversa em espanhol.

## Pré-requisitos

- Feature **Realtime Translation** ativada para a conta pelo Super Admin.
- Integração **Google Translate** ativa na conta, com `project_id` e credenciais válidas. Conecte-a em
  **Configurações → Integrações → Google Translate**. O formulário oferece atalhos para o Google Cloud
  Console e para a documentação oficial: habilite a Cloud Translation API, crie uma conta de serviço
  autorizada e cole o conteúdo completo da chave JSON baixada.
- Acesso de administrador para configurar o padrão do Inbox.
- Acesso à conversa para criar um override específico.

## Passo a passo

### Criar a credencial do Google Translate

1. No formulário da integração, use **Abrir console do Tradutor do Google**. Na página aberta,
   ative a **Cloud Translation API**.
2. No seletor de projetos do Google Cloud, abra os detalhes do projeto. Copie o **ID do projeto** —
   não o nome nem o número — para **Google Cloud Project ID**.
3. Use **Obter credenciais do Tradutor do Google** para abrir **IAM e administrador → Contas de
   serviço** no mesmo projeto.
4. Crie uma conta de serviço, por exemplo **Conversa Labs Translation**.
5. Conceda somente a função **Cloud Translation API User** (`roles/cloudtranslate.user`). Ela permite
   traduzir texto e detectar idiomas sem conceder privilégios de administração.
6. Abra a conta criada e acesse **Chaves → Adicionar chave → Criar nova chave → JSON**. O arquivo é
   baixado uma única vez.
7. Abra o `.json` como texto, copie o objeto completo — incluindo `{`, `}`, `project_id`,
   `private_key` e `client_email` — e cole em **Google Cloud Project Key File**.

O `project_id` do JSON deve ser o mesmo informado no primeiro campo. Guarde o arquivo como segredo e
nunca o envie por conversa, e-mail ou repositório. Se a criação da chave estiver bloqueada, peça ao
administrador do Google Cloud para revisar a política `iam.disableServiceAccountKeyCreation`.

Não configure webhook no Google Cloud. A transcrição de áudio é criada pelo STT nativo da plataforma;
depois, o texto já salvo é traduzido por uma chamada direta à Cloud Translation API. Para usar esse
fluxo, ative **Transcrição de áudio** e também **Tradução automática → Traduzir transcrições** no Inbox.

### Configurar o padrão do Inbox

1. Abra **Configurações → Caixas de entrada** e selecione o Inbox.
2. Abra a aba **Tradução automática**.
3. Ative **Tradução automática**.
4. Escolha o **Idioma padrão da equipe**. Ele é usado apenas quando o agente não definiu uma preferência individual.
5. Escolha um **Idioma de entrega ao contato** ou use **Detectar por conversa**.
6. Defina se o sistema traduz mensagens recebidas, respostas humanas antes do envio e transcrições.
7. Salve e confirme que o indicador mostra **Provedor pronto**.

O Inbox funciona como padrão. Conversas com override podem herdar, ativar ou desativar a tradução sem
alterar as demais.

## Configurações & opções

### Idioma individual do agente

Em **Perfil → Idioma**, cada agente pode definir **Meu idioma para traduções** por conta. Essa escolha:

- muda somente o que aquele agente vê;
- não muda o idioma entregue ao contato;
- não muda a visualização dos colegas;
- é armazenada separadamente para cada conta da qual o usuário participa.

Quando dois agentes usam o mesmo idioma, a tradução já produzida é reutilizada. O sistema não cria uma
chamada ao provedor para cada usuário.

### Exceção por conversa

Na lateral direita do atendimento, abra a seção dedicada **Tradução**. O resumo mostra a política
efetiva, o idioma entregue ao contato, o idioma de visualização do agente, o provedor e as três
direções de tradução sem misturar esses controles com **Informação da conversa**.

Use **Configurar padrão do Inbox** para alterar todas as conversas daquele canal. Use **Ajustar esta
conversa** somente quando este atendimento precisar de uma exceção:

- **Herdar do Inbox**: usa integralmente a política global.
- **Ativar nesta conversa**: permite substituir os idiomas e direções necessárias.
- **Desativar nesta conversa**: interrompe novas traduções automáticas somente nesse atendimento.

A tela também informa o idioma detectado, o idioma de entrega, a origem da configuração e o idioma de
visualização do agente conectado.

O **Idioma de entrega ao contato** definido aqui pertence a esta conversa. Para manter um comportamento
geral, configure o Inbox ou use **Detectar por conversa**; essa opção não grava um idioma permanente no
cadastro do contato nem altera conversas dele em outros Inboxes.

## Casos de uso

### Resposta traduzida antes do envio

Exemplo: o agente escreve em português e o contato deve receber inglês.

1. O texto digitado é preservado.
2. Antes de qualquer chamada ao WhatsApp, Telegram, Instagram, e-mail ou outro canal, o sistema traduz a resposta.
3. A versão em inglês passa a ser o conteúdo canônico realmente transmitido.
4. A bolha do agente continua aparecendo em português, se esse for o idioma de visualização dele.
5. Outro agente pode ver a mesma bolha em espanhol.

Quando as versões são diferentes, a bolha oferece:

- **No meu idioma**: visão principal do agente conectado.
- **Enviado ao contato**: texto exato entregue ao serviço do canal.
- **Texto digitado**: conteúdo escrito pelo atendente antes da tradução.

Webhooks, API e exportações continuam usando o texto realmente transmitido, nunca uma tradução de
visualização particular.

### Mensagens recebidas e áudios

Mensagens recebidas são traduzidas fora do caminho de ingestão, sem bloquear o webhook do canal. A
bolha atualiza por realtime assim que a versão do agente fica pronta e sempre permite consultar o
original.

Para áudios, o STT nativo continua sendo o único responsável por áudio → texto. A tradução usa a
transcrição já armazenada; não baixa a mídia novamente e não gera uma segunda transcrição. Quando a
conversa já possui um idioma detectado, ele orienta o STT; em uma conversa nova ou somente com áudio,
o provedor detecta automaticamente o idioma falado. O player, a velocidade e a posição de reprodução
permanecem independentes da troca entre tradução e original.

## Dicas, limites e boas práticas

### Falhas e segurança operacional

A tradução de saída usa comportamento **fail closed**. Quando ela é obrigatória e o provedor falha:

- nenhum serviço de canal é chamado;
- a mensagem fica com falha recuperável;
- o texto digitado permanece disponível;
- o agente pode corrigir a configuração e usar **Tentar novamente**;
- o sistema nunca envia silenciosamente o texto no idioma errado.

Se o idioma do contato ainda não puder ser detectado, o envio traduzido também é bloqueado até que um
idioma seja definido na conversa. O idioma visual do agente nunca é usado como fallback para o contato.

### Limites da primeira entrega

Não são traduzidos automaticamente: mensagens privadas, campanhas, automações, templates oficiais,
cards estruturados de pagamento/contrato/catálogo/agenda e mensagens criadas por Maestro, AgentBot ou
Captain. Imagens não passam por OCR, e a feature não gera dublagem ou outro arquivo de áudio.

### Privacidade

O conteúdo elegível é processado pela integração Google Translate configurada pelo operador da
instalação. Mensagens e transcrições não são incluídas em logs ou métricas. As traduções acompanham o
mesmo ciclo de retenção e exclusão da mensagem ou do anexo correspondente.

## Solução de problemas

- **Provedor pendente**: revise a integração Google Translate da conta.
- **Idioma do contato não definido**: selecione um idioma na conversa ou aguarde uma mensagem detectável.
- **Minha bolha não mudou de idioma**: confira a preferência no Perfil e reabra a conversa para disparar o catch-up idempotente.
- **A mensagem não foi enviada**: abra o erro da mensagem, corrija o provider/alvo e use Tentar novamente.

## Veja também

- [A tela de conversas: filas, painéis e contexto do contato](/hc/ajuda/articles/tela-de-conversas-pt-br)
- [Configuração de caixas de entrada](/hc/ajuda)