Scuffed Translation

Install, staff-command, configuration and integration reference for server operators. For how translation looks to players see the Scuffed Translation gameplay guide.

• Plugin version: 0.14.7-pre.1 (plugin name ScuffedTranslation)

Requirements

The mod ships no assets. Translation needs a working backend: the default setup works with no key and no extra software.

Chat text is sent to the backend you configure. With gemini or google_free that is a third-party service, so players' chat leaves your server. Use libretranslate on your own host if that matters for your community.

How it works

For each chat message, the mod works out which readers need a translation and then resolves all of their languages together.

1. Who needs it. A reader is skipped if they are the sender, have translation off, read the same language the sender writes, or the message already looks like their language. Messages with no letters, or over maxMessageWords, are left to normal chat.
2. Shorthand. Gamer abbreviations (wru, brb, lfg, idk and others) are expanded to full words.
3. Phrasebook. About 40 common phrases are answered instantly in English, Spanish, Portuguese and French, with no network call (usePhrasebook).
4. Cache. An in-memory LRU cache, saved to disk, holds every language translated for a message. A phrase is only translated once.
5. Masking. Text in double quotes and known item names are swapped for placeholders before the backend sees them and restored afterwards.
6. Backend call. One batched call covers all missing languages. Identical messages that arrive at the same moment share one call.
7. Delivery. The translated line is rendered with the same formatter as a native chat line, with an optional (code) tag, and sent only to the readers of that language. Everyone else keeps normal chat.

If anything fails, the original text is delivered. Translation runs on a small background pool, never on the world thread.

Backends

Routing rules:

• Messages longer than largeMessageWords words skip the primary backend and go to google_free, which saves Gemini requests.
• If the primary reports a quota or rate error (HTTP 429, "quota", "resource exhausted" and similar), it is skipped for quotaBackoffMinutes and fallbackBackend takes over. One warning is logged when this starts and one info line when the primary returns.
• When primary and fallback are both google_free (the keyless setup), a 429 backs off for 15 seconds, doubling on each repeat up to quotaBackoffMinutes, and resets on the first success. Messages in that window are delivered untranslated.
• Requests against the primary are metered by a token bucket. For gemini the bucket is requestsPerMinute. For google_free it is the larger of requestsPerMinute and 60, and for libretranslate the larger of requestsPerMinute and 240. Each language of a per-language backend costs one request. The fallback and long-message backends are not metered by this bucket.
• The background pool queue holds 256 tasks. When it is full, the message is delivered untranslated.

Admin & Staff Commands

All commands are player commands (they cannot be run from the console). The root command is /translate, alias /tr. Every sub-command is visible to the default player group; the staff ones check for operator status themselves and reply with an error otherwise.

Player commands (on, off, set <code>, status, langs) are listed in the gameplay guide. /translate status also prints a "Chat delivered by" line that names who is sending translated chat: the built-in listener, EndlessLink, or "disabled" when builtinChatListener is off. When /translate test works but chat does not, this line shows which component owns chat.

What /translate reload does not apply

translationThreads (the pool is built at startup) and eventPriority (the listener is registered at startup) need a server restart. Everything else in config.json takes effect on reload. On 0.14.7-pre.1 a reload re-reads cache.json without saving first, so translations not yet written to it (fewer than 200) are lost. Later builds save the cache before rebuilding.

Permissions

The mod has one permission node, and it is not a command node.

The /translate command tree itself is assigned to the hytale:Adventurer default group, so every player can use the player sub-commands without any permission setup.

Configuration

File: mods/ScuffedTranslation/config.json. It is written with the defaults below on first start. Edit it, then run /translate reload. Values below a minimum are raised to the minimum.

The file also contains a _comment field that is ignored. An old supportedLanguages key is ignored and logs a line; the language list is fixed in the mod (18 languages, see the gameplay guide) because the in-game font renders Latin and Cyrillic scripts only.

API key setup

Translation works with no key. To use Gemini, create an API key in Google AI Studio and put it in geminiApiKey, then run /translate reload. Keep the key out of shared copies of the file. The key is sent only to Google's Gemini endpoint. If you already use the AIPrefab plugin, its geminiApiKey is reused automatically when the field here is empty.

Cost and rate controls

• The token bucket (requestsPerMinute) and the per-sender limit (perPlayerMessagesPerMinute) cap request volume.
• The phrasebook, the persistent cache and duplicate merging remove most repeat calls.
• largeMessageWords keeps long messages off the metered backend.
• maxMessageWords drops very long messages entirely.
• useContext raises request counts; leave it off unless you need it.

Data & storage

All files are in mods/ScuffedTranslation/ (relative to the server's working directory).

The glossary also harvests every item id from the server registry, including modded items, the first time a player joins. Only multi-word names (2 to 4 words, for example Copper Bar) are indexed.

To clear all translations, stop the server and delete cache.json. To reset one player, remove their UUID from prefs.json.

Integrations

With builtinChatListener set to auto, the built-in listener also steps aside as soon as any chat mod calls the API below. Set it to on to force the built-in listener or off to disable it.

API for other mods

Chat mods that deliver chat themselves can call com.zbeve.scuffedtranslation.ScuffedTranslationApi. It uses only engine types, so it can be reached by reflection without a hard dependency. Get the instance with the static get() (null when the mod is not loaded). Calls can block on a backend request, so make them off the tick thread.

All calls apply the global switch, word limits, per-player throttle, cache and fallback rules described above. All methods except languageOf also mark chat as externally driven.

Troubleshooting