## Overview

Automatic translation lets international support teams work without losing the original conversation
context. Conversa Labs keeps three independent decisions separate:

- **My translation language**: the language each agent uses to view messages and transcripts.
- **Default team language**: the shared fallback defined by the inbox or conversation.
- **Contact delivery language**: the language actually sent through the external channel.

An agent can therefore type and read Portuguese, the contact can receive English, and another agent can
view the same conversation in Spanish.

## Prerequisites

- The account-level **Realtime Translation** feature enabled by the Super Admin.
- An enabled **Google Translate** integration with a valid project id and credentials. Connect it under
  **Settings → Integrations → Google Translate**. The form links to Google Cloud Console and the official
  setup guide: enable the Cloud Translation API, create an authorized service account, and paste the full
  contents of its downloaded JSON key.
- Administrator access to configure inbox defaults.
- Conversation access to create an override.

## Step by step

### Create the Google Translate credential

1. In the integration form, use **Open Google Translate console**. Enable the **Cloud Translation
   API** on the page that opens.
2. Open the Google Cloud project selector and view the project details. Copy the **Project ID** — not
   the name or number — into **Google Cloud Project ID**.
3. Use **Get Google Translate credentials** to open **IAM & Admin → Service Accounts** in the same
   project.
4. Create a service account, for example **Conversa Labs Translation**.
5. Grant only **Cloud Translation API User** (`roles/cloudtranslate.user`). It can translate text and
   detect languages without administrative privileges.
6. Open the new account and select **Keys → Add key → Create new key → JSON**. The file is downloaded
   only once.
7. Open the `.json` as text, copy the entire object — including `{`, `}`, `project_id`, `private_key`
   and `client_email` — and paste it into **Google Cloud Project Key File**.

The JSON `project_id` must match the first field. Keep the file secret and never send it in a
conversation, email or repository. If key creation is blocked, ask your Google Cloud administrator to
review the `iam.disableServiceAccountKeyCreation` organization policy.

Do not configure a Google Cloud webhook. The platform's native STT creates the audio transcript, then
the stored text is translated through a direct Cloud Translation API call. To use this flow, enable
**Audio transcription** and **Automatic translation → Translate transcripts** on the inbox.

### Configure the inbox default

1. Open **Settings → Inboxes** and select an inbox.
2. Open the **Automatic translation** tab.
3. Enable automatic translation.
4. Select the **Default team language**. It is only a fallback for agents without a personal preference.
5. Select a **Contact delivery language** or choose detection per conversation.
6. Choose whether to translate incoming messages, human replies before delivery and transcripts.
7. Save and confirm that the provider indicator is ready.

The inbox is the default. A conversation can inherit, enable or disable translation without changing
other conversations.

## Settings & options

### Set an individual agent language

In **Profile → Language**, each agent can select **My translation language** for the current account.
The preference changes only that agent's view. It never changes contact delivery, a colleague's view or
another account used by the same person. Agents sharing a language reuse the same cached translation.

### Override one conversation

In the conversation's right sidebar, open the dedicated **Translation** section. Its compact summary
shows the effective policy, contact delivery language, agent viewing language, provider and all three
translation directions without mixing them into **Conversation information**.

Use **Configure inbox default** to change all conversations in that channel. Use **Adjust this
conversation** only when the current conversation needs an exception:

- **Inherit from inbox**.
- **Enable for this conversation** and override selected fields.
- **Disable for this conversation** without changing other conversations.

The panel also shows detected language, delivery language, provider state and the current viewer
language source.

The **Contact delivery language** selected here belongs to this conversation. Configure the inbox or
use per-conversation detection for a general behavior; this setting does not persist a language on the
contact record or change that contact's conversations in other inboxes.

## Use cases

### Outbound replies

When an agent types Portuguese and the contact must receive English, the typed text is preserved first.
The reply is translated before any WhatsApp, Telegram, Instagram, email or other channel service is
called. The English result becomes the canonical transmitted content, while each agent sees a localized
view.

When the representations differ, the outgoing bubble provides:

- **My language**: the current agent's primary view.
- **Sent to contact**: the exact content delivered to the channel service.
- **Typed text**: the human-authored source before delivery translation.

Webhooks, APIs and exports continue to use the transmitted content, never a private viewer translation.

### Incoming messages and audio

Incoming translation runs asynchronously and does not block channel ingestion. The bubble updates in
real time and always keeps the original available.

Native STT remains the single audio-to-text owner. Transcript translation uses the stored transcript;
it does not download the media again or create a second transcription. When the conversation already
has a detected language, it is used as the STT hint; in a new or audio-only conversation, the provider
detects the spoken language automatically. Playback state is preserved when switching between original
and translated transcript.

## Tips, limits & best practices

### Failure behavior

Mandatory outbound translation is **fail closed**. If the provider fails, no channel service is called,
the message remains recoverable, the typed text is retained and the agent can retry after fixing the
configuration. The system never silently delivers the wrong language.

If the contact language is still unknown, translated delivery remains blocked. The agent's viewer
language is never used as a contact-language fallback.

### Limits and privacy

The first delivery excludes private messages, campaigns, automations, approved templates, structured
commerce/payment/contract/calendar cards and messages authored by Maestro, AgentBot or Captain. It does
not perform OCR or audio dubbing.

Eligible content is processed by the Google Translate integration configured by the installation
operator. Message text and transcripts are not written to logs or metrics, and translated data follows
the retention lifecycle of its message or attachment.

## Troubleshooting

- **Provider pending**: review the account's Google Translate integration.
- **Contact language missing**: set it on the conversation or wait for a detectable incoming message.
- **My bubble has not changed language**: review the Profile preference and reopen the conversation.
- **Message not sent**: correct the provider/target and use Retry.

## See also

- [The conversations screen: queues, panels and contact context](/hc/ajuda)
- [Inbox configuration](/hc/ajuda)