Zeto Live Chat Translator

# Zeto Chat Translator

Zeto Chat Translator is a server-side Hytale mod that translates player chat messages in real time. Every player can choose their own target language, so an international community can communicate without requiring any client-side installation.

The original game chat event is left untouched for compatibility with other chat-related mods, including Discord bridge integrations. Translations are delivered separately to each player and can also appear as temporary overhead messages above the speaking player.

## Features

Real-time, per-player chat translation
Automatic source-language detection
Individual target language for every player
DeepL, Google Cloud Translation, and LibreTranslate support
Optional translated messages above player characters
Per-player translation and overhead-message toggles
Translation cache to reduce repeated API requests
Server-side only; players do not need to install the mod
Original chat event remains available to Discord bridge and logging mods

## Requirements

A Hytale server capable of loading Java server mods
Java 25, as required by the Hytale server
Internet access from the server when using a hosted translation provider
An API key for DeepL or Google Cloud Translation
LibreTranslate API access, either hosted or self-hosted; an API key may be optional for self-hosted instances

## Installation

1. Stop the server completely.
2. Copy ZetoChatTranslator-1.1.3.jar into the server's mods directory.
3. Make sure no older version of Zeto Chat Translator remains in that directory.
4. Start the server once.
5. The mod will create its configuration file at:

Code:

text
   mods/Zeto_ChatTranslator/config.json

6. Stop the server or edit the file carefully, configure a translation provider, and save the file.
7. Start the server again. Alternatively, an authorized administrator can use /translate reload after editing the configuration.

Do not publish your config.json with a real API key inside it.

## Quick setup with DeepL API Free

DeepL is the default provider. Create a DeepL API key and update these fields:

JSON:

{
  "provider": "deepl",
  "apiKey": "YOUR_DEEPL_API_KEY",
  "endpoint": "https://api-free.deepl.com/v2/translate"
}

For a DeepL API Pro account, use:

Code:

https://api.deepl.com/v2/translate

Restart the server or run /translate reload after saving the configuration.

## Full configuration example

The mod creates and updates this file automatically. The players section is also managed automatically when players use commands.

JSON:

{
  "enabled": true,
  "provider": "deepl",
  "apiKey": "",
  "endpoint": "https://api-free.deepl.com/v2/translate",
  "defaultLanguage": "PL",
  "defaultEnabled": true,
  "showOriginal": true,
  "overheadBubblesEnabled": true,
  "defaultOverheadBubblesEnabled": true,
  "overheadBubbleShowPlayerName": false,
  "overheadBubbleDurationSeconds": 6,
  "overheadBubbleMaxLength": 120,
  "requestTimeoutSeconds": 8,
  "maxMessageLength": 500,
  "cacheMinutes": 10,
  "players": {}
}

## Configuration reference

| Option | Default | Description |
|---|---:|---|
| enabled | true | Globally enables or disables translation processing. |
| provider | deepl | Translation provider: deepl, google, libretranslate, or libre. |
| apiKey | empty | API key used by the selected provider. It may be empty for a self-hosted LibreTranslate instance without authentication. |
| endpoint | DeepL API Free | Full translation API endpoint used by the selected provider. |
| defaultLanguage | PL | Fallback target language for a new player when their client language is unavailable. |
| defaultEnabled | true | Enables translation by default for new players. |
| showOriginal | true | Reserved compatibility option in version 1.1.3. The original game message remains visible regardless of this value. |
| overheadBubblesEnabled | true | Globally enables overhead translated messages. |
| defaultOverheadBubblesEnabled | true | Enables overhead messages by default for new players. |
| overheadBubbleShowPlayerName | false | When true, the speaker's name is displayed above the overhead message. When false, only the message is displayed. |
| overheadBubbleDurationSeconds | 6 | Number of seconds an overhead message remains visible. Accepted range: 2-30. |
| overheadBubbleMaxLength | 120 | Maximum overhead-message length. Accepted range: 20-300 characters. |
| requestTimeoutSeconds | 8 | API connection/request timeout. Accepted range: 2-30 seconds. |
| maxMessageLength | 500 | Messages longer than this value are not translated. Accepted range: 20-2000 characters. |
| cacheMinutes | 10 | How long repeated translations are cached. Accepted range: 0-1440 minutes. Use 0 to disable caching. |
| players | {} | Automatically saved per-player settings, indexed by player UUID. |

Invalid numeric values are automatically limited to the accepted ranges when the configuration is loaded.

## Translation providers

### DeepL API Free

JSON:

{
  "provider": "deepl",
  "apiKey": "YOUR_DEEPL_API_KEY",
  "endpoint": "https://api-free.deepl.com/v2/translate"
}

### DeepL API Pro

JSON:

{
  "provider": "deepl",
  "apiKey": "YOUR_DEEPL_API_KEY",
  "endpoint": "https://api.deepl.com/v2/translate"
}

DeepL documentation: https://developers.deepl.com/api-reference/translate

### Google Cloud Translation Basic (v2)

JSON:

{
  "provider": "google",
  "apiKey": "YOUR_GOOGLE_API_KEY",
  "endpoint": "https://translation.googleapis.com/language/translate/v2"
}

The Cloud Translation API must be enabled for the Google Cloud project associated with the API key.

Google documentation: https://cloud.google.com/translate/docs/reference/rest/v2/translate

### LibreTranslate

Hosted example:

JSON:

{
  "provider": "libretranslate",
  "apiKey": "YOUR_LIBRETRANSLATE_API_KEY",
  "endpoint": "https://libretranslate.com/translate"
}

Self-hosted example without an API key:

JSON:

{
  "provider": "libretranslate",
  "apiKey": "",
  "endpoint": "http://127.0.0.1:5000/translate"
}

If LibreTranslate runs on a different machine or container, replace 127.0.0.1 with an address reachable from the Hytale server.

LibreTranslate documentation: https://docs.libretranslate.com/api/operations/translate/

## Player commands

| Command | Description |
|---|---|
| /translate | Shows the player's current translator status, target language, and active provider. |
| /translate language <code> | Sets the player's target language and enables translation. Example: /translate language en. |
| /translate lang <code> | Alias for /translate language <code>. |
| /translate on | Enables translated messages for the player. |
| /translate off | Disables translated messages for the player. |
| /translate bubble on | Enables overhead translated messages for the player. |
| /translate bubble off | Disables overhead translated messages for the player. |
| /translate bubbletest <text> | Sends a test overhead message to connected viewers. A second nearby player is required to see it. |
| /translate languages | Displays commonly used language codes. |
| /translate reload | Reloads config.json. Requires administrator permission when used by a player. |

Main command aliases: /tlumacz and /translator.

Bubble command aliases: /translate bubbles, /translate dymek, and /translate dymki.

Language command aliases: /translate lang and /translate jezyk.

## Permission

Code:

zeto.chattranslator.admin

This permission is required for a player to use /translate reload. The command can also be executed from the server console.

## Supported language codes

Common codes shown by /translate languages:

Code:

PL, EN, DE, FR, ES, IT, PT, NL, CS, SK, UK, RU, TR, SV, DA, FI,
NO, NB, RO, HU, EL, BG, ET, LV, LT, SL, ID, AR, JA, KO, ZH

Regional codes such as EN-US, EN-GB, PT-BR, and PT-PT are accepted. Actual language availability depends on the selected provider.

## How messages are displayed

The original message remains in normal game chat. A translated line is sent separately to each player who has translation enabled:

Code:

[PL->EN] Send it to me on Discord.

If overhead messages are enabled, each viewer receives the version translated into that viewer's selected language. With overheadBubbleShowPlayerName set to false, only the translated message is displayed above the speaker.

## Overhead-message limitation

Hytale does not render a player's own nameplate above their character. Because the current overhead-message system uses that nameplate, the speaking player cannot see their own overhead message, including in third-person view. A second nearby player is required to test overhead messages.

This does not affect normal chat translations.

## Troubleshooting

### The configuration folder was not created

Check the server log and confirm that the mod loaded successfully. The expected file is:

Code:

mods/Zeto_ChatTranslator/config.json

Also confirm that the server process has permission to write to the mods directory.

### Messages are not translated

Confirm that enabled is true.
Confirm that the provider name is valid.
Verify the API key and endpoint.
Make sure the server can access the internet and the provider's domain.
Check API quotas, billing, and provider-side rate limits.
Run /translate on for the affected player.
Check the server log for HTTP or timeout errors.

### A language is detected incorrectly

Short messages, slang, and text without language-specific characters can be misidentified by translation providers. This is provider-side automatic detection and does not necessarily indicate a mod error.

### Overhead messages are not visible

Confirm that overheadBubblesEnabled is true.
Run /translate bubble on for the viewing player.
Test with a second player standing nearby.
Remember that the speaker cannot see their own overhead message.

### Discord chat forwarding stopped working

Use version 1.1.1 or newer and make sure only one version of Zeto Chat Translator is installed. Current versions leave the original chat event untouched for compatibility with Discord bridge mods.

## Privacy and API usage

Chat messages selected for translation are sent to the configured translation provider. Server owners should disclose this to players when required by local privacy rules or the provider's terms.

Hosted translation services may enforce quotas or charge for usage. Review the selected provider's pricing and usage limits before enabling the mod on a public server.

## Version

Documentation for Zeto Chat Translator 1.1.3.

Zeto Live Chat Translator v1.1.3

Overview History