FTWGL Quake3e Translation System

Downloads

Checksums: SHA256SUMS

• 1. What this is
• 2. What it is for
• 3. Translation backend
• 4. How to use
• 5. Full cvar reference
• 6. Full command reference
• 7. Code changes (overview)
• 8. Troubleshooting
• 9. Known limitations

1. What this is

A chat-translation layer built directly into the FTWGL Quake3e client. It is not a text-file localization table. The client sends chat sentences to a LibreTranslate-compatible HTTP endpoint asynchronously, caches completed translations, and prints them back as [TR] … lines in the console and (optionally) as a chat-style on-screen overlay. The same backend can also be used to translate your own outgoing chat before it reaches the server.

2. What it is for

• Read incoming chat from players who speak a different language without leaving the game.
• Speak to those same players by typing in your own language — the client translates and forwards the message via say / say_team / tell.
• Optionally hide the engine's busy console notify feed so only translated text shows up on screen.

3. Translation backend

The client expects a LibreTranslate-compatible /translate endpoint that accepts application/x-www-form-urlencoded POST fields:

The default endpoint baked into the binary is this host:

https://translate.pugbot.net/translate

You can self-host with Docker:

docker volume create libretranslate-data
docker run -d \
    --name libretranslate \
    --restart unless-stopped \
    -p 127.0.0.1:5000:5000 \
    -v libretranslate-data:/home/libretranslate/.local \
    libretranslate/libretranslate:latest \
    --host 0.0.0.0 \
    --port 5000 \
    --load-only en,es,de,fr,it,pt,ru

Quick connectivity test:

curl -s https://translate.pugbot.net/translate \
    -d 'q=hola amigo como estas' \
    -d 'source=auto' \
    -d 'target=en' \
    -d 'format=text'

Expected response shape:

{"translatedText":"hello friend how are you"}

4. How to use

Incoming translation

Once the client is connected and tr_enable 1 (the default), every chat / radio line that contains a speaker prefix is translated into tr_language. Translated output appears in the console as:

[TR] PlayerName: hello friend how are you

Repeated identical lines are served instantly from the in-memory cache.

On-screen overlay

With tr_overlay 1 (the default), translated lines also appear stacked on the left side of the screen, fading out over tr_overlay_time seconds.

Clean translation mode

Setting cl_clean_tr 1:

• Suppresses the engine's top-left notify feed (kills, hits, connects, server messages).
• Renders the translation overlay in chat-sized (BIGCHAR) text in 640×480 virtual space, roughly where the cgame chat appears.

Outgoing (sent) translation

Two ways to send a translated message:

1. Generic, language from tr_say_lang:

/tr_say hola, ¿cómo estás?
/tr_say_team buena suerte
/tr_tell 3 gracias por la ayuda

2. Per-language shortcut commands (force the target regardless of the cvar):

/say_es hello world         → sends Spanish to public chat
/say_de good luck            → sends German
/say_team_pt vamos no spawn  → sends Portuguese to team chat

While the translation request is in flight nothing is sent yet. When the response arrives the client runs the corresponding say / say_team / tell command with the translated text. If the backend fails or times out, the original message is sent so you are never silenced.

5. Full cvar reference

Core translation

Outgoing translation

Overlay / clean mode

6. Full command reference

Translation control

Outgoing chat

Per-language shortcuts

These ignore tr_say_lang and force the listed target language.

7. Code changes (overview)

The full source patches will be published here once in-game testing is complete and the upstream MR has been opened. High-level layout:

Internals worth knowing

• Cache. A 256-entry ring keyed by "<source>><target>:<lower-cased stripped text>". Each entry stores its own source/target so incoming and outgoing requests with different languages do not collide. Identical repeated lines hit the cache instantly.
• HTTP backend. libcurl multi-handle with bounded request slots (TR_MAX_PENDING = 8) pumped from TR_Frame. Requests use CURLOPT_NOSIGNAL, CURLOPT_TIMEOUT_MS = tr_timeout, CURLOPT_CONNECTTIMEOUT_MS = 750. Response JSON is parsed with a small bespoke parser (no external JSON dependency) supporting \uXXXX escapes.
• Newline / multi-line safety. When the server packs a radio chat message with a follow-up kill notification in the same print buffer (separated by \n), translation only consumes the first line; the trailing remainder is re-appended verbatim so kill feeds never get swallowed.
• Outgoing queue. A 16-slot table records the pending console command (say, say_team, tell <n>) per cache entry. When the matching response arrives the client builds Cbuf_AddText("<cmd> \"<sanitized>\"\n"). Sanitization strips ", \, ; and collapses newlines so the translation can never break out of the quoted argument or inject extra commands.
• Failure fallback. On HTTP error or timeout the original user message is sent unchanged. tr_hide_original falls back to printing the original line.
• Overlay. Lines that pass through TR_EnqueueDisplay are also pushed to an 8-line ring. TR_DrawOverlay renders oldest-first, fading during the last 25% of tr_overlay_time. cl_clean_tr selects between SMALLCHAR (native) and BIGCHAR (640×480 virtual) rendering and gates Con_DrawNotify.
• Recursion guard. When the translator emits its own [TR] lines through Com_Printf, an internal flag short-circuits the translator so it does not try to translate its own output.

8. Troubleshooting

9. Known limitations

• Color codes (^1, ^7, …) are sent to the backend as opaque tokens. Most LibreTranslate models pass them through, but heavy reformatting can lose them. Translated output is then re-prefixed with the speaker's original colored prefix.
• Outgoing translation depends on the server accepting your say / say_team / tell commands. Anti-flood limits still apply.
• The cache is in-memory and not persisted between sessions.
• The translation request queue is bounded; under heavy chat load some lines may be marked failed and shown untranslated.
• Per-language shortcuts cover en/es/de/fr/it/pt/ru. Other languages still work via tr_say_lang <code> + tr_say.