# Translation

## Overview

WaDesk can translate incoming messages and write auto-replies in the customer's own language. You choose which translation provider to use, and WaDesk automatically falls back to a backup provider if one goes down — so a single outage never stops replies.

Two admin screens cover this feature:

- Admin → Translation Providers — set up provider credentials, the default provider, the backup order, and the compliance lockdown.
- Admin → Translation Usage — a read-only dashboard showing volume and estimated cost.

> Works out of the box. MyMemory is active on a fresh install with no API key, so multi-language auto-reply works immediately. Plug in a paid provider only when you want higher quality, self-hosted privacy, or to satisfy a compliance policy.

## The Pre-Seeded Providers

Like Payment Gateways and AI Provider Keys, every translation provider is pre-installed — there is no setup step to add one. You simply fill in credentials, pick a default, and switch it on. These providers are included:

Provider | Type | Credentials | Notes
--- | --- | --- | ---
MyMemory | Free, unofficial | None (optional admin email) | Out-of-box default. ~50k requests/day per IP when an admin email is set.
LibreTranslate | Self-hosted, open-source | Endpoint URL + optional key | Host it yourself via Docker so no customer data leaves your infrastructure.
DeepL | Official, paid | API key | Premium quality, especially for European languages. Free tier ~500k chars/month.
Google Cloud | Official, paid | API key / credentials | Official Google Translate API. Roughly $20 per 1M characters.

> Note: Alongside the four providers above, WaDesk also supports an unofficial free Google (GTX) endpoint. It counts as an unofficial provider for the compliance lockdown (see below).

## Configuring Provider Credentials

On the Translation Providers page each provider is a card. The fields shown depend on the provider — a paid provider shows an API-key field, LibreTranslate shows a server URL field, and MyMemory shows "no credentials required."

1. Type the credentials into the card's fields. Secret fields render as masked password inputs; an already-saved secret shows a `•••••••` placeholder.
2. Optionally set a Sort order (lower = higher priority in the fallback chain).
3. Click Save.

Then toggle the card Activate. Activation is guarded: if any required credential field is still empty, the toggle is blocked with a message telling you which fields to fill — this prevents a half-configured driver from failing silently at runtime.

> Secrets are encrypted, and only saved when changed. Credentials are stored encrypted. Leaving a masked secret field blank keeps the existing value; the audit log records which credential keys changed, never the values.

## The Default & the Fallback Chain

Translation is resilient by design. WaDesk picks a provider in this order:

1. The provider marked Default (if active).
2. Otherwise, the active provider with the lowest Sort order.
3. If a translation fails, WaDesk retries the next active provider in sort order — the backup chain.
4. As a last resort it falls back to the built-in MyMemory provider, and finally to the original (untranslated) text.

### Setting the default

Use a card's Make default button. A provider must be active before it can become the default. Setting a new default automatically clears the flag on the previous one.

### Ordering the chain

Set each provider's Sort order to control retry priority (lower runs first). The default is always tried first; the rest are tried in ascending sort order. A typical paid setup: DeepL as default (sort 0), Google Cloud next (sort 1), and MyMemory last (sort 9) as a free safety net.

## Compliance Lockdown (Official Providers Only)

Some enterprise security policies prohibit routing customer data through unofficial third-party endpoints. The Compliance lockdown panel at the top of the providers page enforces this with one toggle.

When lockdown is ON, the backup chain skips the unofficial / free providers (MyMemory, LibreTranslate, and the free Google GTX endpoint) entirely and routes translation only through the official paid APIs (DeepL and Google Cloud). Skipped providers are greyed out and tagged "Lockdown · skipped" on their cards, and the built-in MyMemory safety net is also disabled.

> Guarded so you can't brick translation. Lockdown refuses to turn on until at least one official paid provider (DeepL or Google Cloud) is both active and configured with a key. If none qualifies, the toggle is rejected with an explanatory message. Both enabling and disabling lockdown are audit-logged.

This setting is platform-wide. (A complementary per-workspace data residency setting can further restrict which providers a given workspace may use, so one install can host EU-strict and unrestricted workspaces side by side.)

## The 24h Cache & Common-Phrases Dictionary

Not every translation calls a provider. Two layers sit in front to cut cost and delay:

- Common-phrases dictionary. A built-in dictionary handles frequent short phrases (greetings, confirmations, common replies) instantly — no provider call at all.
- 24-hour cache. A translated phrase is remembered for 24 hours, so the same incoming text within that window is reused instead of calling the provider again.

Dictionary and cache results are free, and neither appears in the usage dashboard — that page deliberately counts only the provider calls that actually went out. The dashboard estimates roughly how often the cache and dictionary saved you a call.

## The Usage Dashboard

Admin → Translation Usage is a read-only report — nothing on it changes settings. Pick a date range with the From / To filter (it defaults to the current month). It is built for the owner or finance lead who wants to know "what is this translation feature costing me."

### Headline metrics

Card | Meaning
--- | ---
Provider calls | Number of billable calls that went to a provider, plus the estimated % handled by the cache / dictionary instead.
Characters translated | Total characters in and out — the basis for per-character pricing.
Estimated cost | Worked out from each provider's published per-character rate.
Fallback hits | Times the main provider failed and a backup caught it — a high number means your main provider is unreliable.

### Breakdowns

- By provider. Calls, characters, cost, and the published rate per 1M characters for each provider used in the range (free providers show "free").
- Last 30 days. A daily bar chart of characters translated; hover any bar for that day's date, character count, and cost.
- Top spending workspaces. The ten workspaces with the highest translation cost in the range, each linking to its workspace detail page. Useful for spotting which customers drive your translation bill.

> Tip: If a range shows no data, send a non-English message to a connected number that has an auto-reply set up, then refresh — only provider calls are logged here.