Universal Translator: Real-Time Chat Translation

ENGLISH: Discover Jogando Bem! Our multilingual survival server. Here, the chat is translated in real time into your preferred language with the best possible accuracy. Say goodbye to language barriers and come play with us!

PORTUGUÊS: Conheça o Jogando Bem! Nosso servidor de sobrevivência multilíngue. Aqui, o chat é traduzido em tempo real para o idioma de sua preferência, com a melhor precisão possível. Diga adeus às barreiras de idioma e venha jogar com a gente!

ESPAÑOL: Descubre Jogando Bem. Nuestro servidor de supervivencia multilingüe. Aquí, el chat se traduce en tiempo real al idioma de tu preferencia con la mejor precisión posible. ¡Di adiós a las barreras del idioma y ven a jugar con nosotros!

IP: jogandobem.com.br

---

ENGLISH:

Universal Translator

Per-player, automatic chat translation for Hytale servers — with OpenAI running directly inside the mod.

UniversalTranslator intercepts chat messages and delivers each one in the language chosen by every online player. The main pipeline runs entirely inside the mod.jar via the OpenAI API (asynchronous).

---

Overview

• Real-time, per-player translation.
• Simple setup via command (/l) or optional IP-based auto-detection.
• Optional Discord integration (game → Discord and Discord → game).
• Asynchronous execution so it won’t stall the server loop.

---

Key Features

• Individual translation per target language.
• Per-player language command.
• Support for multiple language codes (BCP-47, e.g., pt-BR, en-US, es-AR, and 200+ language-region variants).
• Optional country-based language auto-detection via the free IP Info Lite API (recommended).
• Configurable multilingual plugin messages (messages.json).
• Optional Discord integration via bot and/or webhook.
• Safe fallback when translation fails.
• Runtime config reload with /treload.

---

Requirements

• Hytale server with support for Java plugins.
• Java 21+
• OpenAI API key (required; usage is billed by OpenAI on demand) for direct mode (openai_api_key).
• Optional ipinfo_token for IP-based auto-language (recommended).

---

Installation (Server)

1. Place TradutorUniversal.jar in the server’s plugins/mods folder.
2. Start the server once to generate the configuration files.
3. Edit translator_config.json.
4. Restart the server or run /treload.

---

Default Configuration

translator_config.json (recommended mode):

{
  "default_language": "auto",
  "warn_on_join": true,
  "warn_message": "Server has automatic translation enabled. Use /l <code> to choose your language.",
  "ipinfo_token": "",
  "api_timeout_ms": 60000,
  "pending_ttl_seconds": 30,
  "openai_api_key": "YOUR_OPENAI_KEY",
  "openai_model": "gpt-5-nano" // best cost/benefit in tests (very cheap and great for this use case)
}

Fields

• openai_api_key: OpenAI key (required). Get one by creating an account on the OpenAI platform: https://platform.openai.com/settings/organization/billing/overview (feel free to contact me if you have questions).
• openai_model: Model used for translation (default: gpt-5-nano).
• default_language: Default language when the player hasn’t chosen one.
• warn_on_join: Automatically show a warning/notice on join.
• warn_message: Warning text (not used if language is auto-selected).
• ipinfo_token: Enables country-based auto-language by IP (optional. Get one at https://ipinfo.io/dashboard/lite).
• api_timeout_ms: Timeout for OpenAI calls.
• pending_ttl_seconds: TTL used to correlate pending messages.

---

Commands

• /l — Shows your current language and usage help.
• /l <code> — Sets the player’s language. Example: /l pt-BR
• /l auto — Clears the custom language and returns to the server default.
• /l help <filter> — Lists languages matching a filter (name/code).
• /treload — Reloads configuration and translator stores.

---

How It Works

1. A player sends a chat message.
2. The plugin intercepts the event.
3. The original message is shown immediately to the sender.
4. The plugin groups translation targets by language and requests translations asynchronously, based on each online player’s configured language and/or the Discord chat configuration.
5. Each player receives the version in their configured language. If everyone online at the time of sending uses the same language, messages are not translated to avoid unnecessary paid OpenAI API usage.

---

Performance & Stability

• Translation runs in separate threads (CompletableFuture), without blocking the main tick.
• If translation fails, the system falls back and sends the message exactly as originally written.
• Diagnostic logs help identify response/model issues.

---

Generated Files

• translator_config.json — Main translator configuration.
• languages.json — Per-player language and metadata (auto-generated and auto-filled).
• messages.json — Plugin text per language (for adding more locales).
• discord.json — Discord integration config (optional, recommended).

---

Discord Integration (Optional)

Supports:

• Game → Discord per language.
• Discord → Game with per-player translation.
• Bot token or webhook.
• Online player status.

Remove any other Discord chat-sync mod before enabling this one.

---

For Modders (Architecture)

Core components:

• UniversalTranslator — Plugin bootstrap.
• ChatListener — Chat interception and translation pipeline.
• OpenAiTranslationService — Direct translation via OpenAI.
• TranslationDispatcher — Final per-player delivery.
• LanguageStore / MessageStore / TranslationConfig — Persistence/configuration.
• DiscordIntegration — Discord ↔ game bridge.

Ask for support for your mod if you want an integration, or contribute on the mod’s GitHub page.

---

Privacy & Security

• Chat messages and minimal metadata (names/target languages) are sent to OpenAI in direct mode.
• Protect openai_api_key and do not expose the file publicly.
• Use host-level access controls on the server (optional).

---

Troubleshooting

• ChatTranslation OpenAI invalid output — Update to a recent plugin build and check full logs.
• Players aren’t receiving translated messages — Verify openai_api_key, model selection, and outbound connectivity.
• Auto-language doesn’t work — Confirm a valid ipinfo_token and service availability.

---

Summary

Universal Translator delivers real-time, per-player translation designed for public servers: simple configuration, asynchronous execution, and optional Discord integration.

---

Developed by Brazilians for the world. Visit our Hytale Survival server: jogandobem.com.br

Discord: dc.gg/jogandobem

~ Ferreira_ (Jogando Bem)

---

PORTUGUÊS:

Tradutor Universal

Tradução automática de chat por jogador para servidores Hytale, com OpenAI direto no mod.

TradutorUniversal intercepta mensagens do chat e entrega cada mensagem no idioma escolhido por cada jogador online.
O fluxo principal roda inteiro no mod.jar via API da OpenAI (assíncrono).

---

Visão Geral

• Tradução por jogador em tempo real.
• Configuração simples por comando (/l) ou auto-detecção opcional por IP.
• Integração opcional com Discord (jogo -> Discord e Discord -> jogo).
• Execução assíncrona para não travar o loop do servidor.

---

Recursos Principais

• Tradução individual por idioma de destino.
• Comando de idioma por jogador.
• Suporte a múltiplos códigos de idioma (BCP-47, ex.: pt-BR, en-US, es-AR e mais de 200 variações de idioma-país).
• Auto-detecção de idioma por país via API Grátis IP Info Lite (opcional, mas recomendado).
• Mensagens do plugin multilíngues configuráveis (messages.json).
• Integração com Discord por bot e/ou webhook (opcional).
• Fallback de segurança quando a tradução falha.
• Recarregamento de configurações em runtime com /treload.

---

Requisitos

• Servidor Hytale com suporte a plugins Java.
• Java 21+
• Chave da OpenAI (obrigatória e paga para a OpenAI sob demanda) para o modo direto (openai_api_key).
• ipinfo_token opcional para auto-idioma por IP (recomendado).

---

Instalação (Servidor)

1. Coloque TradutorUniversal.jar na pasta de plugins/mods do servidor.
2. Inicie o servidor uma vez para gerar os arquivos de configuração.
3. Edite translator_config.json.
4. Reinicie o servidor ou use /treload.

---

Configuração Padrão

translator_config.json (modo recomendado):

{
  "default_language": "auto",
  "warn_on_join": true,
  "warn_message": "Servidor com traducao automatica. Use /l <codigo> para escolher o idioma.",
  "ipinfo_token": "",
  "api_timeout_ms": 60000,
  "pending_ttl_seconds": 30,
  "openai_api_key": "SUA_CHAVE_OPENAI",
  "openai_model": "gpt-5-nano" // modelo com melhor custo/benefício nos testes (extremamente barato e bom para esse tipo de uso)
}

Campos

• openai_api_key: chave da OpenAI (obrigatório). Consiga uma fazendo um cadastro na plataforma da OpenAI: https://platform.openai.com/settings/organization/billing/overview (sinta-se livre para me contatar caso tenha dúvidas)
• openai_model: modelo usado na tradução (padrão: gpt-5-nano).
• default_language: idioma padrão quando jogador não escolheu um.
• warn_on_join: aviso automático ao entrar.
• warn_message: texto do aviso (não é usado se o idioma for selecionado automaticamente).
• ipinfo_token: habilita auto-idioma por país (opcional. Consiga um em https://ipinfo.io/dashboard/lite).
• api_timeout_ms: timeout das chamadas OpenAI.
• pending_ttl_seconds: TTL de correlação de mensagens pendentes.

---

Comandos

• /l - Mostra idioma atual e ajuda de uso.
• /l <codigo> - Define idioma do jogador. Ex.: /l pt-BR
• /l auto - Remove idioma customizado e volta ao padrão do servidor.
• /l help <filtro> - Lista idiomas por filtro (nome/código).
• /treload - Recarrega configurações e stores do tradutor.

---

Como Funciona

1. Jogador envia mensagem no chat.
2. O plugin intercepta o evento.
3. A mensagem original é mostrada imediatamente para o remetente.
4. O plugin monta alvos por idioma e solicita tradução de forma assíncrona com base no idioma falado de cada jogador online ou chat configurado no Discord.
5. Cada jogador recebe a versão no idioma configurado para ele. Se todos online no servidor no momento do envio da mensagem, as mensagens não são traduzidas para evitar o uso desnecessário da API paga da OpenAI.

---

Performance e Estabilidade

• Tradução roda em threads separadas (CompletableFuture), sem bloquear o tick principal.
• Em falha de tradução, o sistema aplica fallback e retorna a menasgem exatamente como foi enviada.
• Logs de diagnóstico ajudam a identificar problemas de resposta/modelo.

---

Arquivos Gerados

• translator_config.json - Config principal do tradutor.
• languages.json - Idioma e metadados por jogador (gerado e preenchido automaticamente).
• messages.json - Textos do plugin por idioma. (caso queira configurar mais textos para mais idiomas)
• discord.json - Config da integração Discord (opcional, mas recomendado).

---

Integração com Discord (Opcional)

Suporta:

• Jogo -> Discord por idioma.
• Discord -> Jogo com tradução por jogador.
• Bot token ou webhook.
• Status de players online.

-> Remova qualquer outro mod de sincronização de chat com o discord antes de ativar.

---

Para Modders (Arquitetura)

Componentes centrais:

• TradutorUniversal - Bootstrap do plugin.
• ChatListener - Interceptação do chat e pipeline de tradução.
• OpenAiTranslationService - Tradução direta com OpenAI.
• TranslationDispatcher - Entrega final por jogador.
• LanguageStore / MessageStore / TranslationConfig - Persistência/configuração.
• DiscordIntegration - Bridge Discord <-> jogo.

-> Solicite suporte para seu mod caso queira alguma integração ou contribua na página do mod no Github.

---

Privacidade e Segurança

• Mensagens de chat e metadados mínimos (nomes/idiomas de destino) são enviados para a OpenAI no modo direto.
• Proteja openai_api_key e não exponha o arquivo publicamente.
• Use controles de acesso no host do servidor (opcional).

---

Solução de Problemas

• ChatTranslation OpenAI invalid output - Atualize para build recente do plugin e verifique logs completos.
• Jogadores não recebem mensagem traduzida. Verifique openai_api_key, modelo e conectividade externa.
• Auto-idioma não funciona - Confirme ipinfo_token válido e disponibilidade do serviço.

---

Resumo

O Tradutor Universal entrega tradução em tempo real por jogador com foco em uso prático para servidores públicos: configuração simples, execução assíncrona e integração opcional com Discord.

---

Desenvolvido de brasileiros para o mundo. Visite nosso servidor de Hytale Survival: jogandobem.com.br

Discord: dc.gg/jogandobem

~ Ferreira_ (Jogando Bem)

---

ESPAÑOL:

Traductor Universal

Traducción automática del chat, por jugador, para servidores de Hytale — con OpenAI integrado directamente en el mod.

TraductorUniversal intercepta los mensajes del chat y entrega cada mensaje en el idioma elegido por cada jugador en línea. El flujo principal se ejecuta completamente dentro del mod.jar mediante la API de OpenAI (asíncrono).

---

Visión general

• Traducción en tiempo real por jugador.
• Configuración simple por comando (/l) o autodetección opcional por IP.
• Integración opcional con Discord (juego → Discord y Discord → juego).
• Ejecución asíncrona para no bloquear el bucle del servidor.

---

Funciones principales

• Traducción individual por idioma de destino.
• Comando de idioma por jugador.
• Soporte para múltiples códigos de idioma (BCP-47, p. ej.: pt-BR, en-US, es-AR y más de 200 variantes idioma-país).
• Autodetección de idioma por país mediante la API gratuita IP Info Lite (opcional, pero recomendada).
• Mensajes del plugin multilingües configurables (messages.json).
• Integración con Discord mediante bot y/o webhook (opcional).
• Fallback seguro cuando la traducción falla.
• Recarga de configuración en tiempo de ejecución con /treload.

---

Requisitos

• Servidor de Hytale con soporte para plugins Java.
• Java 21+
• Clave de OpenAI (obligatoria; el uso se factura por OpenAI bajo demanda) para el modo directo (openai_api_key).
• ipinfo_token opcional para auto-idioma por IP (recomendado).

---

Instalación (Servidor)

1. Coloca TradutorUniversal.jar en la carpeta de plugins/mods del servidor.
2. Inicia el servidor una vez para generar los archivos de configuración.
3. Edita translator_config.json.
4. Reinicia el servidor o usa /treload.

---

Configuración predeterminada

translator_config.json (modo recomendado):

{
  "default_language": "auto",
  "warn_on_join": true,
  "warn_message": "Este servidor tiene traducción automática. Usa /l <código> para elegir tu idioma.",
  "ipinfo_token": "",
  "api_timeout_ms": 60000,
  "pending_ttl_seconds": 30,
  "openai_api_key": "TU_CLAVE_OPENAI",
  "openai_model": "gpt-5-nano" // mejor relación costo/beneficio en pruebas (muy barato y excelente para este uso)
}

Campos

• openai_api_key: clave de OpenAI (obligatoria). Consíguela creando una cuenta en la plataforma de OpenAI: https://platform.openai.com/settings/organization/billing/overview (siéntete libre de contactarme si tienes dudas).
• openai_model: modelo usado para traducción (por defecto: gpt-5-nano).
• default_language: idioma predeterminado cuando el jugador no eligió uno.
• warn_on_join: aviso automático al entrar.
• warn_message: texto del aviso (no se usa si el idioma se selecciona automáticamente).
• ipinfo_token: habilita auto-idioma por país vía IP (opcional. consiga um em https://ipinfo.io/dashboard/lite).
• api_timeout_ms: timeout de las llamadas a OpenAI.
• pending_ttl_seconds: TTL para correlación de mensajes pendientes.

---

Comandos

• /l — Muestra el idioma actual y ayuda de uso.
• /l <código> — Define el idioma del jugador. Ej.: /l pt-BR
• /l auto — Elimina el idioma personalizado y vuelve al predeterminado del servidor.
• /l help <filtro> — Lista idiomas por filtro (nombre/código).
• /treload — Recarga configuraciones y stores del traductor.

---

Cómo funciona

1. El jugador envía un mensaje al chat.
2. El plugin intercepta el evento.
3. El mensaje original se muestra inmediatamente al remitente.
4. El plugin agrupa los destinos por idioma y solicita traducciones de forma asíncrona según el idioma configurado de cada jugador en línea y/o el chat de Discord configurado.
5. Cada jugador recibe la versión en su idioma configurado. Si todos los jugadores en línea en el momento del envío usan el mismo idioma, los mensajes no se traducen para evitar uso innecesario de la API paga de OpenAI.

---

Rendimiento y estabilidad

• La traducción corre en hilos separados (CompletableFuture), sin bloquear el tick principal.
• Si falla la traducción, el sistema aplica fallback y devuelve el mensaje exactamente como fue enviado.
• Los logs de diagnóstico ayudan a identificar problemas de respuesta/modelo.

---

Archivos generados

• translator_config.json — Configuración principal del traductor.
• languages.json — Idioma y metadatos por jugador (generado y rellenado automáticamente).
• messages.json — Textos del plugin por idioma (para agregar más idiomas).
• discord.json — Configuración de la integración con Discord (opcional, recomendada).

---

Integración con Discord (Opcional)

Soporta:

• Juego → Discord por idioma.
• Discord → Juego con traducción por jugador.
• Token de bot o webhook.
• Estado de jugadores en línea.

Elimina cualquier otro mod de sincronización de chat con Discord antes de activarlo.

---

Para modders (Arquitectura)

Componentes principales:

• TraductorUniversal — Bootstrap del plugin.
• ChatListener — Interceptación del chat y pipeline de traducción.
• OpenAiTranslationService — Traducción directa con OpenAI.
• TranslationDispatcher — Entrega final por jugador.
• LanguageStore / MessageStore / TranslationConfig — Persistencia/configuración.
• DiscordIntegration — Puente Discord ↔ juego.

Solicita soporte para tu mod si quieres alguna integración, o contribuye en la página del mod en GitHub.

---

Privacidad y seguridad

• Los mensajes del chat y metadatos mínimos (nombres/idiomas de destino) se envían a OpenAI en el modo directo.
• Protege openai_api_key y no expongas el archivo públicamente.
• Usa controles de acceso en el host del servidor (opcional).

---

Solución de problemas

• ChatTranslation OpenAI invalid output — Actualiza a una build reciente del plugin y revisa los logs completos.
• Los jugadores no reciben mensajes traducidos — Verifica openai_api_key, el modelo y la conectividad externa.
• El auto-idioma no funciona — Confirma un ipinfo_token válido y la disponibilidad del servicio.

---

Resumen

El Traductor Universal ofrece traducción en tiempo real por jugador, enfocada en uso práctico para servidores públicos: configuración simple, ejecución asíncrona e integración opcional con Discord.

---

Desarrollado por brasileños para el mundo. Visita nuestro servidor Hytale Survival: jogandobem.com.br

Discord: dc.gg/jogandobem

~ Ferreira_ (Jogando Bem)

---