Translate

Sprachen pro Spieler, Übersetzungsdateien, übersetzte Schilder und optionale KI-Chat-Übersetzung.

Privatv0.2.0Hilfsmittel

BenötigtTypeWriter0.9.0-beta-177 (BTC build)GUIoptionalMySQLoptionalMiniPlaceholdersoptional

Für das BornToCraft-Netzwerk entwickelt. Diese Erweiterung ist zu Referenzzwecken dokumentiert und wird nicht verteilt.

Support

Überblick

Translate lässt jeden Spieler eine Sprache wählen und die Inhalte deines Servers darin lesen. Du deklarierst die Sprachen in einem Konfigurations-Entry, schreibst die Texte in JSON-Dateien (das Format ist mit dem Plugin Triton kompatibel, bestehende Dateien lassen sich also weiterverwenden) und zeigst sie überall dort an, wo MiniMessage-Platzhalter akzeptiert werden, mit <translate_key:your.key>. Jeder Spieler sieht den Text in seiner eigenen Sprache, mit Rückgriff auf eine andere Sprache, wenn ein Text fehlt.

Drei optionale Funktionen setzen darauf auf: übersetzte Schilder (ein Schild zeigt seinen Text in der Sprache dessen, der es ansieht), ein Sprachmenü und Einstellungsmenü, die als gewöhnliche GUI-Pages gebaut werden, und KI-Chat-Übersetzung, bei der Chatnachrichten für Betrachter, die eine andere Sprache sprechen, über einen KI-Anbieter oder eine Übersetzungs-Engine übersetzt werden.

Die Wahl der Spieler wird in Artifacts gespeichert. Die Sprache wird pro Spieler gespeichert, ebenso die Opt-ins für Schild- und Chat-Übersetzung.

Funktionen

• Sprachliste — jede Sprache hat einen Code, eine Banner-Flagge, einen Anzeigenamen, Client-Locales, Fallbacks und Aktionen, die bei der Wahl ausgeführt werden.
• JSON-Dateien im Triton-Stil — Text- und Schildübersetzungen mit den Argumenten %1, %2, aus einem Ordner geladen und ohne Neustart neu ladbar.
• Fallback-Kette — angeforderte Sprache, dann ihre fallbackLanguages, dann die Hauptsprache.
• Automatische Erkennung — optional zur Sprache wechseln, die zur Client-Locale passt.
• Übersetzte Schilder — platziere Text an Schild-Koordinaten; Spieler können sich im Einstellungsmenü abmelden.
• Über Pages deklarierte Menüs — baue das Sprach- und das Einstellungsmenü als GUI-Pages mit Translate-Button-Typen.
• KI-Chat-Übersetzung — OpenRouter, OpenAI, DeepSeek, Groq, Mistral, Ollama, Anthropic, Gemini, LibreTranslate, DeepL oder jeder OpenAI-kompatible Server, mit Cache.
• Sprach-Events und -Facts — löse Entries aus, wenn ein Spieler die Sprache ändert, und teste die aktuelle Sprache in Criteria.

Installation

1. Installiere die Erweiterung GUI, um das Sprach- und das Einstellungsmenü zu verwenden (optional, wenn du nur den Befehl nutzt).
2. Installiere optional die Erweiterung MySQL: Der Cache der KI-Übersetzung wird dann in der Datenbank gespeichert, andernfalls liegt er nur im Speicher.
3. Lege die Translate-JAR in plugins/Typewriter/extensions/ ab und starte den Server neu.
4. Erstelle den Ordner plugins/Typewriter/Translate/ (er wird beim ersten Laden automatisch erstellt) und lege deine .json-Übersetzungsdateien darin ab.
5. Installiere MiniPlaceholders, wenn du Übersetzungen über Platzhalter anzeigen möchtest.

Erste Schritte

1. Öffne im TypeWriter-Web-Panel eine statische Page und füge ein Player Language-Artifact hinzu: Ohne es wird die gewählte Sprache nicht gespeichert.
2. Füge einen Translation Config-Entry hinzu. Füge in languages en_GB und fr_FR hinzu: Setze jeweils name, flag (ein Banner-Code), displayName (zum Beispiel &3Francais), minecraftCodes (fr_FR, fr_CA) und optional fallbackLanguages. Setze mainLanguage auf en_GB.
3. Erstelle plugins/Typewriter/Translate/messages.json mit diesem Inhalt und veröffentliche dann oder führe /translate reload aus:

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

4. Verwende <translate_key:welcome.message> in jedem MiniMessage-Text mit Platzhaltern (einem Dialog, einem Hologramm, einem Scoreboard). Ein Spieler, der /translate fr_FR ausführt, sieht nun den französischen Text.
5. Damit Spieler über ein Menü wählen können, baue mit der Erweiterung GUI eine Menü-Page, platziere darauf die Items translate_button:LANGUAGE#0, LANGUAGE#1 ..., verweise in languageMenu der Konfiguration darauf und löse Open Language Selector aus.

hinweis

Die Text-Argumente %1, %2 werden nur von Code gefüllt, der die Übersetzungs-API mit Argumenten aufruft. Der Platzhalter <translate_key:...> nimmt nur einen Schlüssel entgegen, daher bleibt %1 dort unverändert stehen.

Funktionsweise

Die Sprache eines Spielers wird in dieser Reihenfolge bestimmt: die gespeicherte Wahl, dann die zur Client-Locale passende Sprache (minecraftCodes), dann mainLanguage.

Übersetzungsdateien

Dateien sind .json-Dateien direkt im Übersetzungsordner (translationsFolder, standardmäßig Translate, innerhalb von plugins/Typewriter/). Jede Datei ist ein Array von Elementen; eine Datei kann auch ein Objekt sein, das ein solches Array unter translations, items, languages, data oder entries enthält. Elemente ohne gültigen type und key werden übersprungen, und eine Datei, die sich nicht parsen lässt, wird protokolliert und ignoriert.

Ein Text-Element hat einen key und ein languages-Objekt. &-Farbcodes werden umgewandelt. Die Schlüsselsuche ist tolerant: exakter Schlüssel, dann der Schlüssel mit den Präfixen lang_, lang. oder default., dann ohne Beachtung der Groß- und Kleinschreibung, dann ein Abgleich mit dem Teil nach dem letzten _ oder ..

Ein Schild-Element hat locations (world, x, y, z) und lines pro Sprache. Bis zu 8 Zeilen werden gelesen, aber nur die ersten 4 (Vorderseite) werden angezeigt.

{
  "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", "", ""]
  }
}

Ein Schild wird übersetzt, wenn ein Spieler es an einem aufgeführten Ort platziert oder bearbeitet oder es rechtsklickt; der Spieler sieht seine Sprache über ein clientseitiges Update auf dem Schild. Spieler, die die Schildübersetzung im Einstellungsmenü ausgeschaltet haben, sehen das Original.

Menüs

Das Sprach- und das Einstellungsmenü sind normale open_gui-Entries der Erweiterung GUI. Translate stellt Button-Typen bereit, die du an deren Items platzierst (das Feld für den Button-Typ eines GUI-Items):

Button-Typ	Verhalten
translate_button:LANGUAGE#<n>	Die n-te Sprache der Konfiguration (ab 0). Zeigt den Code und eine Markierung bei der aktiven; ein Linksklick wählt sie aus. Leer nach der letzten Sprache.
translate_button:TOGGLE_CHAT	Zeigt die KI-Chat-Übersetzung des Spielers an und schaltet sie um (standardmäßig an).
translate_button:TOGGLE_SIGN	Zeigt die Schildübersetzung des Spielers an und schaltet sie um (standardmäßig an).

Verweise in der Translation Config auf die Pages: languageMenu (und languageMenuViewId für eine bestimmte Ansicht) für die Auswahl, settingsMenu (und settingsMenuViewId) für die Einstellungen. Öffne sie mit Open Language Selector oder Open Translation Settings. /translate menu öffnet das Sprachmenü. Ist openSelectorCommandOverride gesetzt, wird stattdessen dieser Befehl von der Konsole ausgeführt ({player} wird durch den Spielernamen ersetzt).

Die Sprachauswahl aus dem Menü benötigt ein Player-Language-Artifact: Ohne eines wird dem Spieler mitgeteilt, dass die Wahl nicht gespeichert würde. Die Schalter benötigen ebenso die Artifacts Player AI Preference und Player Sign Preference.

KI-Chat-Übersetzung

Konfiguriere aiTranslation in der Translation Config. Setze enabled, wähle einen provider und gib einen apiKey an. Die Basis-URL und das Modell entsprechen standardmäßig denen des Anbieters, sofern nicht apiBaseUrl oder model gesetzt ist; OPENAI_COMPATIBLE erfordert apiBaseUrl. Verwende bevorzugt env:VAR_NAME als apiKey, um den Schlüssel aus einer Umgebungsvariablen zu lesen, statt ihn in der Page zu speichern.

Wenn ein Spieler chattet, wird die Nachricht in die Sprache jedes Betrachters übersetzt, dessen Sprache sich von der des Absenders unterscheidet und der die Chat-Übersetzung eingeschaltet hat. Der übersetzte Text ersetzt die Nachricht im Chat des Betrachters, und beim Darüberfahren wird das Original angezeigt. Der Chat wartet höchstens chatTranslationTimeoutMs (standardmäßig 800 ms) auf Übersetzungen und zeigt dann den Betrachtern, die noch warten, die unübersetzte Nachricht. Nachrichten, die noTranslateRegex entsprechen (standardmäßig Befehle und reine Zahlen), werden nicht gesendet, Text, der censorRegex entspricht, wird vor dem Senden durch *** ersetzt, und enabledSections muss CHAT enthalten.

Nach drei fehlgeschlagenen Anfragen in Folge schaltet sich die KI-Übersetzung bis zum nächsten Neuladen der Übersetzungen selbst ab. Ergebnisse werden nach Nachricht und Sprache zwischengespeichert, in der Datenbank, wenn die MySQL-Erweiterung vorhanden ist, andernfalls im Speicher.

Befehle

Der Befehl ist /translate, mit den Aliasen /lang und /language. Er kann nur von Spielern ausgeführt werden.

Befehl	Beschreibung
/translate	Zeigt die Hilfe.
/translate <language>	Setzt deine Sprache anhand ihres konfigurierten Namens (zum Beispiel fr_FR).
/translate list	Listet die konfigurierten Sprachen auf und markiert deine.
/translate menu	Öffnet die Sprachauswahl.
/translate toggle_ai	Schaltet die KI-Chat-Übersetzung für dich um.
/translate sign set <key>	Markiert das Schild, das du ansiehst (innerhalb von 5 Blöcken), als mit diesem Schlüssel übersetzt. Erfordert typewriter.translate.admin.
/translate sign remove	Entfernt die Markierung vom Schild. Erfordert typewriter.translate.admin.
/translate sign info	Zeigt Schlüssel, Ort und Übersetzung des Schilds. Erfordert typewriter.translate.admin.
/translate reload	Lädt die Übersetzungsdateien neu. Erfordert typewriter.translate.admin.

/translate sign set schreibt nur eine Markierung und den Schlüssel auf das Schild. Der eigentliche Text stammt aus einem sign-Element in einer JSON-Datei mit dem Ort des Schilds.

Berechtigungen

Berechtigung	Gewährt
typewriter.translate.admin	/translate reload und /translate sign ....

Platzhalter

MiniPlaceholders-Expansion translate, nutzbar als MiniMessage-Tags. Übersetzter Text darf MiniMessage-Markup und verschachtelte Platzhalter enthalten.

Platzhalter	Gibt zurück
<translate_key:some.key>	Den Text zu diesem Schlüssel in der Sprache des Betrachters. Fehlt er, [Translation not found: key] in Rot.
<translate_lang>	Den Sprachcode des Betrachters, etwa fr_FR.
<translate_lang_display>	Den Anzeigenamen der Sprache.
<translate_lang_flag>	Den Banner-Flaggencode der Sprache.
<translate_count>	Anzahl der geladenen Übersetzungen (Texte plus Schilder).
<translate_languages>	Anzahl der konfigurierten Sprachen.

Entries

10 Einträge, aus dem Quellcode der Erweiterung generiert.

Aktionen4

• 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

Ereignisse1

• Player Language Change EventTriggered when a player changes their language

Fakten1

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

Artefakte3

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

Manifeste1

• Translation ConfigConfigure the multi-language translation system

Fehlerbehebung

[Translation not found: key] erscheint. Der Schlüssel steht in keiner geladenen Datei, oder die Datei konnte nicht geladen werden. Suche im Server-Log nach Failed to load translation file, validiere das JSON und führe /translate reload aus. Stelle sicher, dass die Datei direkt in plugins/Typewriter/Translate/ liegt (Unterordner werden nicht gelesen) und die Endung .json hat.

Die Sprache wird bei jedem Login zurückgesetzt. Es ist kein Player-Language-Artifact veröffentlicht, die Wahl wird also nicht gespeichert. Füge eines hinzu.

Das Menü bewirkt nichts. Das Log meldet No 'languageMenu' configured oder No 'settingsMenu' configured: Setze die Menü-Page in der Translation Config. Beim Sprachmenü hat openSelectorCommandOverride Vorrang, wenn es nicht leer ist.

Die Sprache folgt nicht der Client-Sprache. Ohne gespeicherte Wahl wird die Client-Locale automatisch verwendet, wenn sie in minecraftCodes einer Sprache vorkommt. forceClientLocaleOnJoin wechselt den Spieler zusätzlich und überschreibt seine gespeicherte Wahl, wann immer der Client einen Locale-Wechsel meldet, der zu einer anderen Sprache passt.

Die KI-Übersetzung funktioniert nicht mehr. Suche im Log nach AUTOMATICALLY DISABLED: Drei aufeinanderfolgende API-Fehler schalten sie ab. Korrigiere Schlüssel, URL oder Modell und führe dann /translate reload aus. apiKey references env var ... not set bedeutet, dass die Umgebungsvariable fehlt.

Ein Schild wird nicht übersetzt. Das Schild muss exakt an den Koordinaten stehen, die in einem sign-Element einer JSON-Datei aufgeführt sind, im richtigen Weltnamen. Der Spieler darf die Schildübersetzung nicht ausgeschaltet haben, und das Schild wird beim Platzieren oder Rechtsklicken übersetzt.

Verwandte Erweiterungen

• TinyEssentials — sein Chatformat bleibt erhalten, wenn die KI-Übersetzung den Chat-Renderer umhüllt.
• MySQL — persistenter Cache der KI-Übersetzung.