# Chat in every language, read aloud

> One chat, everybody reads it in their own language: a chain of translators (Groq, Azure, DeepL, LibreTranslate) with budgets, a cache and the original on hover - and chat read aloud on the player's own computer with the STYGION Keystone Voice mod. New in 0.4, off by default; the voice has 31 languages from Keystone Voice 1.1.

Source: https://stygion.eu/docs/keystone/translate
Updated: 2026-11-16

New in Keystone 0.4. The translator is the module `translate`: off until you set `enabled = true` in `config/keystone/translate.toml` (or in **Settings**) and restart the server - a module's `enabled` is read once, when the server starts. Reading aloud is on the player's side, with the small mod STYGION Keystone Voice, and every player turns it on for themselves.

## What players see

One chat for everybody. A line written in another language arrives a moment later in the reader's own, with a small mark in front of it - `[CS] <Ada> who's going mining?`. Readers of the writer's language, and the writer, get the line at once; nobody's line waits for somebody else's translation. A line that cannot be translated in time (`patience`, 6 seconds) arrives as written - a translation never loses a line.

Whether a reader can see what was really written is **the server's choice**, `original`:

| `original` | What the mark does |
|---|---|
| `hover` (default) | hovering the mark shows the language, the translator and the original |
| `click` | the same, and a click copies the original |
| `off` | the mark says it was translated, the original is not shown |

Each player decides for themselves (permission `keystone.translate`, which the default group has):

- `/translate` - what happens now; `/translate on`, `/translate off`;
- `/translate to <language>` - read chat in another language than the game's (`cs`, `de`, ... or `auto` for the game's language);
- with Keystone on the client: **Keystone Settings (K) → Language & voice**, a switch and the language.

Which language a player reads is their choice, otherwise their game's language. `players.default` decides whether somebody who never chose reads translations (on); `languages` narrows what chat is translated into (empty = whatever each player reads); `pairs` (for example `cs>en, sk>en, en>cs`) translates only the listed language pairs, so a reader no pair goes into costs no request (empty = any language into the reader's).

## The translators

`chain` lists them in the order they are asked; the first that can answer wins, and when none can, the line is shown as written.

| Id | What | Free tier | What you set |
|---|---|---|---|
| `groq` | a language model - reads typos, slang and mixed languages the way a player meant them | Groq's free tier (requests a minute and a day) | `groq.key`; `groq.address` and `groq.model` point it at any OpenAI-compatible service (OpenAI, OpenRouter, your own Ollama) |
| `azure` | Azure AI Translator | F0: 2 million characters a month | `azure.key`, `azure.region` for a regional resource |
| `deepl` | DeepL API | Free: 500,000 characters a month | `deepl.key`; `deepl.address` is the Pro address for a Pro key; `deepl.english` EN-GB or EN-US |
| `libre` | LibreTranslate | your own server has no limit | `libre.address`, `libre.key` only if it asks for one |

A translator without its key (or address) is skipped. Each has `<id>.enabled`, `<id>.monthly-characters` (a budget of ours; Azure and DeepL default to their free tier, 0 = none) and `<id>.per-minute` (a ceiling of requests a minute). A translator that answers "too many" rests for a minute and longer each time, one whose month is spent rests six hours, a refused key half an hour; the console says so once. Months are counted in UTC from the 1st - a provider's own billing month may start on another day.

What saves requests:

- a **cache** of translations (`cache.entries`, `cache.keep`): a repeated line costs nothing;
- a line going to two languages asks once first - the answer says what language it is in, so a Czech line is never sent off to be translated into Czech;
- `writers-language = own` takes a line to be in the language its writer reads (half the requests, more mistakes; the default `detect` checks every line);
- `most-characters` (300) and `per-player.per-minute` (12): longer lines, and a writer over their share, are shown as written - a spammer does not spend your month.

Translators on this machine or your network need `allow-local`. The addresses, the keys, `chain` and `allow-local` are the owner's settings only.

## Watching it

The editor's **Chat translation** screen shows every translator in the chain's order with its state (ready, off, not set up, resting, month spent, at its ceiling), this month's characters against the budget, requests and failures, and a box to try a line through the whole chain. The same is `GET /v1/translate/usage` (scope `translate.read`); `POST /v1/translate/try` (`text`, `to`; scope `translate.write`) translates without anybody reading it and counts against the month, `POST /v1/translate/forget` empties the cache. In the console or for staff: `/keystone translate` (permission `keystone.translate.admin`).

## What leaves the server

> [!IMPORTANT]
> With the module on and a translator set up, **the text of chat lines goes to that translation service** - no names, no ids, nothing else. Say so in your server's rules.

- Nothing is sent before a key or an address is set; the module starts off, every translator can be switched off and every player can turn it off for themselves.
- The swear filter replaces words before a line goes out, and a translation goes through it again on the way back, so a translator cannot put a swear word in somebody's mouth. A translation is one line, without colour codes, never far longer than what was written.
- Keys stay in `translate.toml` and are sent only to their own service; the API and the editor say whether a key is set, never what it is.
- The player's choice (on or off, a language code) is stored on the server in `keystone.db`.

To change lines per reader, Keystone writes chat lines itself while the translator is on, as with the swear filter; if another mod formats chat and `chat.step-aside` is on, Keystone steps aside and nothing is translated (the console says so once).

## Chat read aloud: STYGION Keystone Voice 1.1

Reading chat aloud is a mod of its own, **STYGION Keystone Voice** (`keystone_voice`, one jar for 1.21.1 and 26.2).
Keystone decides which lines are read, in which language and with which name, and draws the settings (K → Settings →
Language & voice); without the voice mod that tab says where to get it.

Voice 1.1 speaks **31 languages with one natural voice** (Supertonic 3, female or male, 44.1 kHz) on the sherpa-onnx
2.0.1 runtime, in a small Java process of its own beside the game - Windows, Linux and macOS, x64 and ARM64. Nothing is
downloaded until the player presses Download: about 155 MB once (the model from Hugging Face pinned to one commit,
the runtime from its GitHub release), every file checked against a SHA-256 in the mod, into `config/keystone/tts/`;
after that everything is offline. Delete the folder to remove it. A line is read in the language the server names
for it, else the reader's own; the Piper files of 1.0 are deleted once the new voice is there.

In K → Settings → Language & voice: on or off, a female or a male voice, whether to say who wrote a line, whether to read your own lines, speed (50 to 200 %), volume, Download, Try the voice, and the list of languages the voice reads. For addons: `ChatVoice` and `ChatVoices` in the API's `client` package let another mod be the voice. The voice model Supertonic 3 (Supertone Inc.) is under the OpenRAIL-M licence, sherpa-onnx under Apache-2.0.
