Translate

Langues par joueur, fichiers de traduction, panneaux traduits et traduction de chat par IA optionnelle.

Privéesv0.2.0Utilitaires

NécessiteTypeWriter0.9.0-beta-177 (BTC build)GUIfacultatifMySQLfacultatifMiniPlaceholdersfacultatif

Conçue pour le réseau BornToCraft. Cette extension est documentée à titre de référence et n'est pas distribuée.

Support

Présentation

Translate permet à chaque joueur de choisir une langue et de lire le contenu de votre serveur dans cette langue. Vous déclarez les langues dans une entrée de configuration, écrivez les textes dans des fichiers JSON (le format est compatible avec le plugin Triton, les fichiers existants peuvent donc être réutilisés), et les affichez partout où les placeholders MiniMessage sont acceptés avec <translate_key:your.key>. Chaque joueur voit le texte dans sa propre langue, avec repli sur une autre langue lorsqu'un texte manque.

Trois fonctionnalités facultatives s'y ajoutent : des panneaux traduits (un panneau affiche son texte dans la langue de celui qui le regarde), un menu de langue et un menu de paramètres construits comme de simples pages GUI, et la traduction du chat par IA, où les messages du chat sont traduits pour les spectateurs qui parlent une autre langue via un fournisseur d'IA ou un moteur de traduction.

Les choix des joueurs sont stockés dans des artifacts. La langue est sauvegardée par joueur, tout comme les préférences d'activation de la traduction des panneaux et du chat.

Fonctionnalités

• Liste de langues — chaque langue a un code, un drapeau de bannière, un nom d'affichage, des locales client, des langues de repli et des actions à exécuter lorsqu'elle est choisie.
• Fichiers JSON de style Triton — traductions de textes et de panneaux, avec des arguments %1, %2, chargées depuis un dossier et rechargeables sans redémarrage.
• Chaîne de repli — langue demandée, puis ses fallbackLanguages, puis la langue principale.
• Détection automatique — passe éventuellement à la langue correspondant à la locale du client.
• Panneaux traduits — placez du texte aux coordonnées d'un panneau ; les joueurs peuvent s'en désinscrire dans le menu des paramètres.
• Menus déclarés par des pages — construisez les menus de langue et de paramètres sous forme de pages GUI avec les types de boutons de Translate.
• Traduction du chat par IA — OpenRouter, OpenAI, DeepSeek, Groq, Mistral, Ollama, Anthropic, Gemini, LibreTranslate, DeepL ou tout serveur compatible OpenAI, avec un cache.
• Événements et facts de langue — déclenchez des entrées lorsqu'un joueur change de langue et testez la langue actuelle dans des critères.

Installation

1. Installez l'extension GUI pour utiliser les menus de langue et de paramètres (facultatif si vous n'utilisez que la commande).
2. Installez éventuellement l'extension MySQL : le cache de traduction par IA est alors sauvegardé dans la base de données, sinon il ne vit qu'en mémoire.
3. Placez le JAR de Translate dans plugins/Typewriter/extensions/ et redémarrez le serveur.
4. Créez le dossier plugins/Typewriter/Translate/ (il est créé automatiquement au premier chargement) et placez-y vos fichiers de traduction .json.
5. Installez MiniPlaceholders si vous voulez afficher les traductions via des placeholders.

Premiers pas

1. Dans le panneau web de TypeWriter, ouvrez une page statique et ajoutez un artifact Player Language : sans lui, la langue choisie n'est pas sauvegardée.
2. Ajoutez une entrée Translation Config. Dans languages, ajoutez en_GB et fr_FR : pour chacune, définissez name, flag (un code de bannière), displayName (par exemple &3Francais), minecraftCodes (fr_FR, fr_CA) et éventuellement fallbackLanguages. Définissez mainLanguage sur en_GB.
3. Créez plugins/Typewriter/Translate/messages.json avec ce contenu, puis publiez ou exécutez /translate reload :

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

4. Utilisez <translate_key:welcome.message> dans n'importe quel texte MiniMessage avec placeholders (un dialogue, un hologramme, un scoreboard). Un joueur qui exécute /translate fr_FR voit désormais le texte en français.
5. Pour laisser les joueurs choisir depuis un menu, construisez une page de menu avec l'extension GUI, placez-y des objets translate_button:LANGUAGE#0, LANGUAGE#1..., référencez-la dans languageMenu de la configuration, et déclenchez Open Language Selector.

remarque

Les arguments de texte %1, %2 ne sont renseignés que par du code qui appelle l'API de traduction avec des arguments. Le placeholder <translate_key:...> ne prend qu'une clé ; %1 y reste donc tel quel.

Fonctionnement

La langue d'un joueur est déterminée dans cet ordre : le choix sauvegardé, puis la langue correspondant à la locale du client (minecraftCodes), puis mainLanguage.

Fichiers de traduction

Les fichiers sont des fichiers .json placés directement dans le dossier des traductions (translationsFolder, Translate par défaut, dans plugins/Typewriter/). Chaque fichier est un tableau d'éléments ; un fichier peut aussi être un objet qui contient un tel tableau sous translations, items, languages, data ou entries. Les éléments sans type ni key valides sont ignorés, et un fichier qui ne peut pas être analysé est consigné dans le journal puis ignoré.

Un élément text possède une key et un objet languages. Les codes de couleur & sont convertis. La recherche de clé est tolérante : clé exacte, puis la clé avec les préfixes lang_, lang. ou default., puis sans tenir compte de la casse, puis une correspondance sur la partie après le dernier _ ou ..

Un élément sign possède des locations (world, x, y, z) et des lines par langue. Jusqu'à 8 lignes sont lues, mais seules les 4 premières (face avant) sont affichées.

{
  "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 panneau est traduit lorsqu'un joueur le place ou le modifie à un emplacement listé, ou fait un clic droit dessus ; le joueur voit sa langue sur le panneau grâce à une mise à jour côté client. Les joueurs qui ont désactivé la traduction des panneaux dans le menu des paramètres voient l'original.

Menus

Les menus de langue et de paramètres sont des entrées open_gui normales de l'extension GUI. Translate fournit des types de boutons à placer sur leurs objets (le champ de type de bouton d'un objet GUI) :

Type de bouton	Comportement
translate_button:LANGUAGE#<n>	La n-ième langue de la configuration (à partir de 0). Affiche le code et un marqueur sur la langue active ; un clic gauche la sélectionne. Vide au-delà de la dernière langue.
translate_button:TOGGLE_CHAT	Affiche et bascule la traduction du chat par IA du joueur (activée par défaut).
translate_button:TOGGLE_SIGN	Affiche et bascule la traduction des panneaux du joueur (activée par défaut).

Référencez les pages dans la Translation Config : languageMenu (et languageMenuViewId pour une vue précise) pour le sélecteur, settingsMenu (et settingsMenuViewId) pour les paramètres. Ouvrez-les avec Open Language Selector ou Open Translation Settings. /translate menu ouvre le menu de langue. Si openSelectorCommandOverride est défini, cette commande est exécutée par la console à la place ({player} est remplacé par le nom du joueur).

La sélection de la langue depuis le menu nécessite un artifact Player Language : sans lui, le joueur est informé que son choix ne serait pas sauvegardé. Les interrupteurs nécessitent de même les artifacts Player AI Preference et Player Sign Preference.

Traduction du chat par IA

Configurez aiTranslation dans la Translation Config. Activez enabled, choisissez un provider et renseignez une apiKey. L'URL de base et le modèle sont par défaut ceux du fournisseur, sauf si apiBaseUrl ou model est défini ; OPENAI_COMPATIBLE exige apiBaseUrl. Préférez env:VAR_NAME comme apiKey pour lire la clé depuis une variable d'environnement plutôt que de la stocker dans la page.

Lorsqu'un joueur écrit dans le chat, le message est traduit dans la langue de chaque spectateur dont la langue diffère de celle de l'expéditeur et qui a activé la traduction du chat. Le texte traduit remplace le message dans le chat du spectateur, et le survoler affiche l'original. Le chat attend au plus chatTranslationTimeoutMs (800 ms par défaut) les traductions, puis affiche le message non traduit aux spectateurs encore en attente. Les messages qui correspondent à noTranslateRegex (commandes et nombres seuls par défaut) ne sont pas envoyés, le texte qui correspond à censorRegex est remplacé par *** avant l'envoi, et enabledSections doit contenir CHAT.

Après trois requêtes échouées d'affilée, la traduction par IA se désactive d'elle-même jusqu'au prochain rechargement des traductions. Les résultats sont mis en cache par message et par langue, dans la base de données si l'extension MySQL est présente et en mémoire sinon.

Commandes

La commande est /translate, avec les alias /lang et /language. Elle ne peut être exécutée que par des joueurs.

Commande	Description
/translate	Affiche l'aide.
/translate <language>	Définit votre langue par son nom configuré (par exemple fr_FR).
/translate list	Liste les langues configurées et marque la vôtre.
/translate menu	Ouvre le sélecteur de langue.
/translate toggle_ai	Bascule pour vous la traduction du chat par IA.
/translate sign set <key>	Marque le panneau que vous regardez (à moins de 5 blocs) comme traduit avec cette clé. Nécessite typewriter.translate.admin.
/translate sign remove	Retire la marque du panneau. Nécessite typewriter.translate.admin.
/translate sign info	Affiche la clé, l'emplacement et la traduction du panneau. Nécessite typewriter.translate.admin.
/translate reload	Recharge les fichiers de traduction. Nécessite typewriter.translate.admin.

/translate sign set n'écrit qu'un marqueur et la clé sur le panneau. Le texte réel provient d'un élément sign d'un fichier JSON avec l'emplacement du panneau.

Permissions

Permission	Autorise
typewriter.translate.admin	/translate reload et /translate sign ....

Placeholders

Expansion MiniPlaceholders translate, utilisable sous forme de balises MiniMessage. Le texte traduit peut contenir du balisage MiniMessage et des placeholders imbriqués.

Placeholder	Renvoie
<translate_key:some.key>	Le texte de cette clé dans la langue du spectateur. S'il manque, [Translation not found: key] en rouge.
<translate_lang>	Le code de langue du spectateur, tel que fr_FR.
<translate_lang_display>	Le nom d'affichage de la langue.
<translate_lang_flag>	Le code du drapeau de bannière de la langue.
<translate_count>	Nombre de traductions chargées (textes plus panneaux).
<translate_languages>	Nombre de langues configurées.

Entrées

10 entrées, générées depuis la source de l'extension.

Actions4

• 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

Événements1

• Player Language Change EventTriggered when a player changes their language

Faits1

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

Artefacts3

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

Manifestes1

• Translation ConfigConfigure the multi-language translation system

Dépannage

[Translation not found: key] apparaît. La clé ne figure dans aucun fichier chargé, ou le fichier n'a pas pu être chargé. Consultez le journal du serveur à la recherche de Failed to load translation file, validez le JSON, et exécutez /translate reload. Assurez-vous que le fichier se trouve directement dans plugins/Typewriter/Translate/ (les sous-dossiers ne sont pas lus) et qu'il a l'extension .json.

La langue se réinitialise à chaque connexion. Aucun artifact Player Language n'est publié ; le choix n'est donc pas stocké. Ajoutez-en un.

Le menu ne fait rien. Le journal indique No 'languageMenu' configured ou No 'settingsMenu' configured : définissez la page de menu dans la Translation Config. Pour le menu de langue, openSelectorCommandOverride a priorité lorsqu'il n'est pas vide.

La langue ne suit pas la langue du client. Sans choix sauvegardé, la locale du client est utilisée automatiquement si elle figure dans les minecraftCodes d'une langue. forceClientLocaleOnJoin fait en plus basculer le joueur, et écrase son choix sauvegardé, chaque fois que le client signale un changement de locale qui correspond à une autre langue.

La traduction par IA ne fonctionne plus. Cherchez AUTOMATICALLY DISABLED dans le journal : trois échecs d'API consécutifs la désactivent. Corrigez la clé, l'URL ou le modèle, puis exécutez /translate reload. apiKey references env var ... not set signifie que la variable d'environnement est absente.

Un panneau n'est pas traduit. Le panneau doit se trouver exactement aux coordonnées listées dans un élément sign d'un fichier JSON, dans le bon nom de monde. Le joueur ne doit pas avoir désactivé la traduction des panneaux, et le panneau est traduit lorsqu'il est placé ou qu'on fait un clic droit dessus.

Extensions associées

• TinyEssentials — son format de chat est conservé lorsque la traduction par IA enveloppe le moteur de rendu du chat.
• MySQL — cache persistant de la traduction par IA.