Translate

Idiomas por jugador, archivos de traducción, carteles traducidos y traducción de chat con IA opcional.

Privadasv0.2.0Utilidades

RequiereTypeWriter0.9.0-beta-177 (BTC build)GUIopcionalMySQLopcionalMiniPlaceholdersopcional

Creada para la red BornToCraft. Esta extensión está documentada como referencia y no se distribuye.

Soporte

Descripción general

Translate permite que cada jugador elija un idioma y lea en él el contenido de tu servidor. Declaras los idiomas en una entrada de configuración, escribes los textos en archivos JSON (el formato es compatible con el plugin Triton, por lo que se pueden reutilizar archivos existentes) y los muestras en cualquier lugar que admita placeholders de MiniMessage con <translate_key:your.key>. Cada jugador ve el texto en su propio idioma, con recurso a otro idioma cuando falta un texto.

Se añaden tres funciones opcionales: carteles traducidos (un cartel muestra su texto en el idioma de quien lo mira), un menú de idiomas y un menú de ajustes construidos como páginas de GUI normales, y la traducción del chat con IA, en la que los mensajes del chat se traducen para los espectadores que hablan otro idioma mediante un proveedor de IA o un motor de traducción.

Las elecciones de los jugadores se almacenan en artefactos. El idioma se guarda por jugador, igual que la aceptación de la traducción de carteles y de chat.

Características

• Lista de idiomas: cada idioma tiene un código, una bandera de banner, un nombre visible, locales del cliente, idiomas de reserva y acciones que ejecutar al elegirlo.
• Archivos JSON al estilo Triton: traducciones de texto y de carteles, con argumentos %1, %2, cargadas desde una carpeta y recargables sin reiniciar.
• Cadena de reserva: el idioma solicitado, después sus fallbackLanguages y después el idioma principal.
• Detección automática: cambia opcionalmente al idioma que coincide con el locale del cliente.
• Carteles traducidos: coloca texto en las coordenadas de los carteles; los jugadores pueden desactivarlo en el menú de ajustes.
• Menús declarados en páginas: construye los menús de idioma y de ajustes como páginas de GUI con tipos de botón de Translate.
• Traducción del chat con IA: OpenRouter, OpenAI, DeepSeek, Groq, Mistral, Ollama, Anthropic, Gemini, LibreTranslate, DeepL o cualquier servidor compatible con OpenAI, con caché.
• Eventos y hechos de idioma: activa entradas cuando un jugador cambia de idioma y comprueba el idioma actual en los criterios.

Instalación

1. Instala la extensión GUI para usar los menús de idioma y de ajustes (opcional si solo usas el comando).
2. Opcionalmente, instala la extensión MySQL: la caché de traducción con IA se guarda entonces en la base de datos; en caso contrario, solo vive en memoria.
3. Coloca el JAR de Translate en plugins/Typewriter/extensions/ y reinicia el servidor.
4. Crea la carpeta plugins/Typewriter/Translate/ (se crea automáticamente en la primera carga) y coloca en ella tus archivos de traducción .json.
5. Instala MiniPlaceholders si quieres mostrar traducciones mediante placeholders.

Primeros pasos

1. En el panel web de TypeWriter, abre una página estática y añade un artefacto Player Language: sin él no se guarda el idioma elegido.
2. Añade una entrada Translation Config. En languages, añade en_GB y fr_FR: para cada uno establece name, flag (un código de banner), displayName (por ejemplo &3Francais), minecraftCodes (fr_FR, fr_CA) y, opcionalmente, fallbackLanguages. Establece mainLanguage en en_GB.
3. Crea plugins/Typewriter/Translate/messages.json con este contenido, y después publica o ejecuta /translate reload:

[
  {
    "type": "text",
    "key": "welcome.message",
    "languages": {
      "en_GB": "&6Welcome to the server, %1!",
      "fr_FR": "&6Bienvenue sur le serveur, %1 !"
    }
  }
]

4. Usa <translate_key:welcome.message> en cualquier texto MiniMessage con placeholders (un diálogo, un holograma, un scoreboard). Un jugador que ejecute /translate fr_FR verá ahora el texto en francés.
5. Para que los jugadores elijan desde un menú, construye una página de menú con la extensión GUI, coloca en ella objetos translate_button:LANGUAGE#0, LANGUAGE#1..., hazle referencia en languageMenu de la configuración y activa Open Language Selector.

nota

Los argumentos de texto %1, %2 solo los rellena el código que llama a la API de traducción con argumentos. El placeholder <translate_key:...> solo recibe una clave, así que %1 se queda tal como está escrito.

Cómo funciona

El idioma de un jugador se resuelve en este orden: la elección guardada, después el idioma que coincide con el locale del cliente (minecraftCodes) y por último mainLanguage.

Archivos de traducción

Los archivos son archivos .json situados directamente en la carpeta de traducciones (translationsFolder, Translate por defecto, dentro de plugins/Typewriter/). Cada archivo es una matriz de elementos; un archivo también puede ser un objeto que contenga esa matriz bajo translations, items, languages, data o entries. Los elementos sin un type y una key válidos se omiten, y un archivo que no se puede analizar se registra en el log y se ignora.

Un elemento de texto tiene una key y un objeto languages. Los códigos de color & se convierten. La búsqueda de claves es tolerante: la clave exacta, después la clave con los prefijos lang_, lang. o default., después sin distinguir mayúsculas y, por último, una coincidencia con la parte posterior al último _ o ..

Un elemento de cartel tiene locations (world, x, y, z) y lines por idioma. Se leen hasta 8 líneas, pero solo se muestran las 4 primeras (cara frontal).

{
  "type": "sign",
  "key": "shop.sign",
  "locations": [{"world": "world", "x": 100, "y": 64, "z": 200}],
  "lines": {
    "en_GB": ["&b[Shop]", "&fClick to open", "", ""],
    "fr_FR": ["&b[Boutique]", "&fCliquez pour ouvrir", "", ""]
  }
}

Un cartel se traduce cuando un jugador lo coloca o lo edita en una ubicación enumerada, o hace clic derecho en él; el jugador ve su idioma en el cartel mediante una actualización en el cliente. Los jugadores que han desactivado la traducción de carteles en el menú de ajustes ven el original.

Menús

Los menús de idioma y de ajustes son entradas open_gui normales de la extensión GUI. Translate proporciona tipos de botón que se colocan en sus objetos (el campo de tipo de botón de un objeto de GUI):

Tipo de botón	Comportamiento
translate_button:LANGUAGE#<n>	El n-ésimo idioma de la configuración (desde 0). Muestra el código y una marca en el idioma activo; el clic izquierdo lo selecciona. Vacío pasado el último idioma.
translate_button:TOGGLE_CHAT	Muestra y cambia la traducción del chat con IA del jugador (activada por defecto).
translate_button:TOGGLE_SIGN	Muestra y cambia la traducción de carteles del jugador (activada por defecto).

Haz referencia a las páginas en la Translation Config: languageMenu (y languageMenuViewId para una vista concreta) para el selector, y settingsMenu (y settingsMenuViewId) para los ajustes. Ábrelas con Open Language Selector o Open Translation Settings. /translate menu abre el menú de idiomas. Si openSelectorCommandOverride está definido, la consola ejecuta ese comando en su lugar ({player} se sustituye por el nombre del jugador).

La selección de idioma desde el menú necesita un artefacto Player Language: sin él, se avisa al jugador de que la elección no se guardaría. Los interruptores necesitan igualmente los artefactos Player AI Preference y Player Sign Preference.

Traducción del chat con IA

Configura aiTranslation en la Translation Config. Establece enabled, elige un provider y proporciona una apiKey. La URL base y el modelo toman por defecto los del proveedor, salvo que se establezca apiBaseUrl o model; OPENAI_COMPATIBLE requiere apiBaseUrl. Es preferible usar env:VAR_NAME como apiKey para leer la clave de una variable de entorno en lugar de almacenarla en la página.

Cuando un jugador escribe en el chat, el mensaje se traduce al idioma de cada espectador cuyo idioma difiera del del remitente y que tenga activada la traducción del chat. El texto traducido sustituye al mensaje en el chat del espectador y, al pasar el cursor sobre él, se muestra el original. El chat espera como máximo chatTranslationTimeoutMs (800 ms por defecto) las traducciones y después muestra el mensaje sin traducir a los espectadores que siguen esperando. Los mensajes que coinciden con noTranslateRegex (comandos y números puros por defecto) no se envían, el texto que coincide con censorRegex se sustituye por *** antes de enviarlo, y enabledSections debe contener CHAT.

Tras tres solicitudes fallidas seguidas, la traducción con IA se desactiva hasta la siguiente recarga de las traducciones. Los resultados se almacenan en caché por mensaje e idioma, en la base de datos si la extensión MySQL está presente y en memoria en caso contrario.

Comandos

El comando es /translate, con los alias /lang y /language. Solo pueden ejecutarlo los jugadores.

Comando	Descripción
/translate	Muestra la ayuda.
/translate <language>	Establece tu idioma por su nombre configurado (por ejemplo fr_FR).
/translate list	Lista los idiomas configurados y marca el tuyo.
/translate menu	Abre el selector de idioma.
/translate toggle_ai	Activa o desactiva para ti la traducción del chat con IA.
/translate sign set <key>	Marca el cartel al que miras (a un máximo de 5 bloques) como traducido con esta clave. Requiere typewriter.translate.admin.
/translate sign remove	Quita la marca del cartel. Requiere typewriter.translate.admin.
/translate sign info	Muestra la clave, la ubicación y la traducción del cartel. Requiere typewriter.translate.admin.
/translate reload	Recarga los archivos de traducción. Requiere typewriter.translate.admin.

/translate sign set solo escribe un marcador y la clave en el cartel. El texto real procede de un elemento sign de un archivo JSON con la ubicación del cartel.

Permisos

Permiso	Concede
typewriter.translate.admin	/translate reload y /translate sign ....

Placeholders

Expansión de MiniPlaceholders translate, utilizable como etiquetas MiniMessage. El texto traducido puede contener marcado MiniMessage y placeholders anidados.

Placeholder	Devuelve
<translate_key:some.key>	El texto de esta clave en el idioma del espectador. Si falta, [Translation not found: key] en rojo.
<translate_lang>	El código de idioma del espectador, como fr_FR.
<translate_lang_display>	El nombre visible del idioma.
<translate_lang_flag>	El código de la bandera de banner del idioma.
<translate_count>	Número de traducciones cargadas (textos más carteles).
<translate_languages>	Número de idiomas configurados.

Entradas

10 entradas, generadas a partir del código fuente de la extensión.

Acciones4

• Open Language Selector ActionOpen the language selection menu
• Open Translation Settings ActionOpen the translation settings menu
• Reload Translations ActionReload translation files from disk
• Set Language ActionSet a player's translation language

Eventos1

• Player Language Change EventTriggered when a player changes their language

Hechos1

• Player Language FactReturns the player's current language as a numeric value

Artefactos3

• Player Ai Preference ArtifactStores player AI translation preferences
• Player Language ArtifactStores player language preferences
• Player Sign Preference ArtifactStores player sign translation preferences

Manifiestos1

• Translation ConfigConfigure the multi-language translation system

Resolución de problemas

Aparece [Translation not found: key]. La clave no está en ningún archivo cargado, o el archivo no se pudo cargar. Busca Failed to load translation file en el registro del servidor, valida el JSON y ejecuta /translate reload. Asegúrate de que el archivo está directamente en plugins/Typewriter/Translate/ (no se leen las subcarpetas) y tiene la extensión .json.

El idioma se restablece en cada inicio de sesión. No hay ningún artefacto Player Language publicado, por lo que la elección no se almacena. Añade uno.

El menú no hace nada. El registro dice No 'languageMenu' configured o No 'settingsMenu' configured: establece la página del menú en la Translation Config. Para el menú de idiomas, openSelectorCommandOverride tiene prioridad cuando no está vacío.

El idioma no sigue al idioma del cliente. Sin una elección guardada, el locale del cliente se usa automáticamente si aparece en minecraftCodes de un idioma. forceClientLocaleOnJoin además cambia al jugador, y sobrescribe su elección guardada, siempre que el cliente informe de un cambio de locale que coincida con otro idioma.

La traducción con IA dejó de funcionar. Busca AUTOMATICALLY DISABLED en el registro: tres fallos consecutivos de la API la desactivan. Corrige la clave, la URL o el modelo y ejecuta /translate reload. apiKey references env var ... not set significa que falta la variable de entorno.

Un cartel no se traduce. El cartel debe estar exactamente en las coordenadas enumeradas en un elemento sign de un archivo JSON, en el nombre de mundo correcto. El jugador no debe haber desactivado la traducción de carteles, y el cartel se traduce cuando se coloca o se hace clic derecho en él.

Extensiones relacionadas

• TinyEssentials: se conserva su formato de chat cuando la traducción con IA envuelve el renderizador del chat.
• MySQL: caché persistente de la traducción con IA.