feat: add hybrid localisation support with per-player locale resolution (#1062)

Adds multi-language support using a server-wide default locale with
optional per-player override (similar to LuckPerms/EssentialsX).

- Introduce MessageRegistry with immutable Snapshot for thread-safe
  atomic swaps during hot-reloads
- Refactor Message class to use deferred resolution, applying token
  replacements at resolve time with locale-aware lookups
- Add locale cascading fallback (e.g. zh_tw -> zh -> default)
- Migrate messages from single messages.yml to messages/ directory
  with per-locale files (messages_en.yml, etc.), retaining messages.yml
  as a backward-compatible overlay
- Add locale config (locale.default, locale.perPlayer) to config.yml
- Persist player locale in bm_players table (VARCHAR(16)) via V2
  database migration, gated by perPlayerLocale config
- Add locale-aware kick(Message) and broadcast(Message, String) APIs
  to CommonPlayer and CommonServer
- Migrate all kick() and broadcast() call sites (17 kick, 26 broadcast)
  to the new Message-based overloads
- Implement platform-specific getLocale() across Bukkit, Bungee,
  Velocity, Sponge (API7+API8), and Fabric (with pre-1.21 fallback)
- Add locale-aware DateUtils overloads for localised time formatting
- Log loaded locales and missing key diagnostics on startup
- Add comprehensive tests: MessageRegistry, Message deferred resolution,
  locale normalisation, player storage locale persistence, DB migration
- Add E2E locale smoke test with German locale fixture
- Update E2E sync-configs.sh to distribute messages/ directories

Author: confuser

bukkit/src/main/java/me/confuser/banmanager/bukkit/BukkitPlayer.java

@@ -7,6 +7,7 @@
 import me.confuser.banmanager.common.kyori.text.TextComponent;
 import me.confuser.banmanager.common.kyori.text.serializer.gson.GsonComponentSerializer;
 import me.confuser.banmanager.common.util.Message;
+import me.confuser.banmanager.common.util.MessageRegistry;
 import me.confuser.banmanager.common.util.UUIDUtils;
 import net.md_5.bungee.chat.ComponentSerializer;
 import org.bukkit.Bukkit;
@@ -125,6 +126,13 @@ public boolean isOnline() {
     return getPlayer() != null;
   }
 
+  @Override
+  public String getLocale() {
+    Player p = getPlayer();
+    if (p == null) return "en";
+    return MessageRegistry.normaliseLocale(p.getLocale());
+  }
+
   private Player getPlayer() {
     if (player != null) return player;
     if (isOnlineMode()) return Bukkit.getServer().getPlayer(uuid);

bukkit/src/main/java/me/confuser/banmanager/bukkit/listeners/JoinListener.java

@@ -60,8 +60,9 @@ private class BanJoinHandler implements CommonJoinHandler {
     @Override
     public void handlePlayerDeny(PlayerData player, Message message) {
       plugin.getServer().callEvent("PlayerDeniedEvent", player, message);
-
-      handleDeny(message);
+      String locale = player.getLocale() != null ? player.getLocale() : "en";
+      event.setLoginResult(AsyncPlayerPreLoginEvent.Result.KICK_BANNED);
+      event.setKickMessage(BukkitServer.formatMessage(message.resolve(locale)));
     }
 
     @Override

bungee/src/main/java/me/confuser/banmanager/bungee/BungeePlayer.java

@@ -6,6 +6,7 @@
 import me.confuser.banmanager.common.data.PlayerData;
 import me.confuser.banmanager.common.kyori.text.TextComponent;
 import me.confuser.banmanager.common.util.Message;
+import me.confuser.banmanager.common.util.MessageRegistry;
 import net.md_5.bungee.api.ProxyServer;
 import net.md_5.bungee.api.connection.ProxiedPlayer;
 import net.md_5.bungee.chat.ComponentSerializer;
@@ -110,6 +111,13 @@ public boolean canSee(CommonPlayer player) {
     return true;
   }
 
+  @Override
+  public String getLocale() {
+    java.util.Locale locale = player.getLocale();
+    if (locale == null) return "en";
+    return MessageRegistry.normaliseLocale(locale.toString());
+  }
+
   private ProxiedPlayer getPlayer() {
     return ProxyServer.getInstance().getPlayer(uuid);
   }

bungee/src/main/java/me/confuser/banmanager/bungee/listeners/JoinListener.java

@@ -58,8 +58,9 @@ private class BanJoinHandler implements CommonJoinHandler {
     @Override
     public void handlePlayerDeny(PlayerData player, Message message) {
       plugin.getServer().callEvent("PlayerDeniedEvent", player, message);
-
-      handleDeny(message);
+      String locale = player.getLocale() != null ? player.getLocale() : "en";
+      event.setCancelled(true);
+      event.setCancelReason(BungeeServer.formatMessage(message.resolve(locale)));
     }
 
     @Override

common/src/main/java/me/confuser/banmanager/common/BanManagerPlugin.java

@@ -14,16 +14,19 @@
 import me.confuser.banmanager.common.ormlite.logger.LocalLog;
 import me.confuser.banmanager.common.ormlite.support.ConnectionSource;
 import me.confuser.banmanager.common.ormlite.support.DatabaseConnection;
+import me.confuser.banmanager.common.configuration.file.YamlConfiguration;
 import me.confuser.banmanager.common.runnables.Runner;
 import me.confuser.banmanager.common.storage.*;
 import me.confuser.banmanager.common.storage.global.*;
 import me.confuser.banmanager.common.storage.migration.MigrationRunner;
 import me.confuser.banmanager.common.storage.mariadb.MariaDBDatabase;
 import me.confuser.banmanager.common.storage.mysql.MySQLDatabase;
 import me.confuser.banmanager.common.util.DriverManagerUtil;
+import me.confuser.banmanager.common.util.Message;
+import me.confuser.banmanager.common.util.MessageRegistry;
 
-import java.io.File;
-import java.io.IOException;
+import java.io.*;
+import java.nio.file.Files;
 import java.sql.SQLException;
 
 import static java.lang.Long.parseLong;
@@ -153,6 +156,9 @@ public class BanManagerPlugin {
   @Getter
   private PlaceholderResolver placeholderResolver;
 
+  @Getter
+  private MessageRegistry messageRegistry;
+
   public BanManagerPlugin(PluginInfo pluginInfo, CommonLogger logger, File dataFolder, CommonScheduler scheduler, CommonServer server, CommonMetrics metrics) {
     this.pluginInfo = pluginInfo;
     this.logger = logger;
@@ -268,18 +274,126 @@ public final void disable() {
   }
 
   public void setupConfigs() {
-    MessagesConfig newMessagesConfig = new MessagesConfig(dataFolder, logger);
-    if (!newMessagesConfig.load()) {
-      logger.warning("Failed to reload messages.yml, keeping previous messages");
-    }
-
     config = reloadConfig(new DefaultConfig(dataFolder, logger), config, "config.yml");
     consoleConfig = reloadConfig(new ConsoleConfig(dataFolder, logger), consoleConfig, "console.yml");
     schedulesConfig = reloadConfig(new SchedulesConfig(dataFolder, logger), schedulesConfig, "schedules.yml");
     exemptionsConfig = reloadConfig(new ExemptionsConfig(dataFolder, logger), exemptionsConfig, "exemptions.yml");
     reasonsConfig = reloadConfig(new ReasonsConfig(dataFolder, logger), reasonsConfig, "reasons.yml");
     geoIpConfig = reloadConfig(new GeoIpConfig(dataFolder, logger), geoIpConfig, "geoip.yml");
     webhookConfig = reloadConfig(new WebhookConfig(dataFolder, logger), webhookConfig, "webhooks.yml");
+
+    loadMessages();
+  }
+
+  private void loadMessages() {
+    String defaultLocale = config != null ? config.getDefaultLocale() : "en";
+    MessageRegistry newRegistry = new MessageRegistry(defaultLocale);
+
+    copyMessagesDirectory();
+
+    File messagesDir = new File(dataFolder, "messages");
+    if (messagesDir.exists() && messagesDir.isDirectory()) {
+      File[] files = messagesDir.listFiles((dir, name) ->
+          name.startsWith("messages_") && name.endsWith(".yml"));
+
+      if (files != null) {
+        for (File file : files) {
+          String fileName = file.getName();
+          String locale = fileName.substring("messages_".length(), fileName.length() - ".yml".length());
+          loadLocaleFile(newRegistry, file, locale);
+        }
+      }
+    }
+
+    File legacyMessages = new File(dataFolder, "messages.yml");
+    if (legacyMessages.exists()) {
+      loadLocaleFile(newRegistry, legacyMessages, defaultLocale);
+    }
+
+    if (!newRegistry.hasAnyMessages()) {
+      if (messageRegistry != null) {
+        logger.warning("No messages loaded, keeping previous messages");
+        return;
+      }
+    }
+
+    if (messageRegistry != null) {
+      messageRegistry.atomicSwap(newRegistry);
+    } else {
+      messageRegistry = newRegistry;
+    }
+
+    Message.init(messageRegistry, logger);
+
+    logLocaleInfo();
+  }
+
+  private void logLocaleInfo() {
+    if (messageRegistry == null) return;
+
+    java.util.Set<String> locales = messageRegistry.getAvailableLocales();
+    logger.info("Loaded " + locales.size() + " locale(s): " + String.join(", ", locales));
+
+    String defaultLocale = messageRegistry.getDefaultLocale();
+    for (String locale : locales) {
+      if (locale.equals(defaultLocale)) continue;
+      int missing = messageRegistry.getMissingKeyCount(locale);
+      if (missing > 0) {
+        logger.info("Locale '" + locale + "' is missing " + missing + " key(s) (will fall back to '" + defaultLocale + "')");
+      }
+    }
+  }
+
+  private void loadLocaleFile(MessageRegistry registry, File file, String locale) {
+    try {
+      YamlConfiguration conf = new YamlConfiguration();
+      conf.load(file);
+
+      if (conf.getConfigurationSection("messages") == null) {
+        logger.warning("Messages section not found in " + file.getName() + ", skipping");
+        return;
+      }
+
+      java.util.Map<String, String> messages = new java.util.HashMap<>();
+
+      for (String key : conf.getConfigurationSection("messages").getKeys(true)) {
+        String value = conf.getString("messages." + key);
+        if (value != null) {
+          messages.put(key, value.replace("\\n", "\n").replaceAll("(?<=\\n)(?=\\n)", " "));
+        }
+      }
+
+      if (!messages.isEmpty()) {
+        java.util.Map<String, String> existing = registry.getMessages(locale);
+        if (!existing.isEmpty()) {
+          java.util.Map<String, String> merged = new java.util.HashMap<>(existing);
+          merged.putAll(messages);
+          registry.loadLocale(locale, merged);
+        } else {
+          registry.loadLocale(locale, messages);
+        }
+      }
+    } catch (Exception e) {
+      logger.warning("Failed to load " + file.getName(), e);
+    }
+  }
+
+  private void copyMessagesDirectory() {
+    File messagesDir = new File(dataFolder, "messages");
+    if (!messagesDir.exists()) {
+      messagesDir.mkdirs();
+    }
+
+    File defaultMessages = new File(messagesDir, "messages_en.yml");
+    if (!defaultMessages.exists()) {
+      try (InputStream in = getClass().getClassLoader().getResourceAsStream("messages/messages_en.yml")) {
+        if (in != null) {
+          Files.copy(in, defaultMessages.toPath());
+        }
+      } catch (IOException e) {
+        logger.warning("Failed to copy default messages_en.yml", e);
+      }
+    }
   }
 
   /**

common/src/main/java/me/confuser/banmanager/common/CommonPlayer.java

@@ -12,6 +12,10 @@ public interface CommonPlayer extends CommonSender {
 
   void kick(String message);
 
+  default void kick(Message message) {
+    kick(message.resolveFor(this));
+  }
+
   void sendMessage(String message);
 
   void sendMessage(Message message);
@@ -43,4 +47,6 @@ public interface CommonPlayer extends CommonSender {
   boolean teleport(CommonWorld world, double x, double y, double z, float pitch, float yaw);
 
   boolean canSee(CommonPlayer player);
+
+  String getLocale();
 }

common/src/main/java/me/confuser/banmanager/common/CommonServer.java

@@ -3,6 +3,7 @@
 import me.confuser.banmanager.common.api.events.CommonEvent;
 import me.confuser.banmanager.common.commands.CommonSender;
 import me.confuser.banmanager.common.kyori.text.TextComponent;
+import me.confuser.banmanager.common.util.Message;
 
 import java.util.UUID;
 
@@ -17,6 +18,15 @@ public interface CommonServer {
 
   void broadcast(String message, String permission);
 
+  default void broadcast(Message message, String permission) {
+    for (CommonPlayer player : getOnlinePlayers()) {
+      if (player.hasPermission(permission)) {
+        player.sendMessage(message.resolveFor(player));
+      }
+    }
+    getConsoleSender().sendMessage(message.toString());
+  }
+
   void broadcastJSON(TextComponent message, String permission);
 
   void broadcast(String message, String permission, CommonSender sender);

common/src/main/java/me/confuser/banmanager/common/commands/BanCommand.java

@@ -167,7 +167,7 @@ public boolean onCommand(CommonSender sender, CommandParser parser) {
       if (onlinePlayer != null) {
         final Message finalKickMessage = kickMessage;
         getPlugin().getScheduler().runSync(() -> {
-          onlinePlayer.kick(finalKickMessage.toString());
+          onlinePlayer.kick(finalKickMessage);
         });
       }
     });

common/src/main/java/me/confuser/banmanager/common/commands/BanIpCommand.java

@@ -130,7 +130,7 @@ public boolean onCommand(CommonSender sender, CommandParser parser) {
 
         for (CommonPlayer onlinePlayer : getPlugin().getServer().getOnlinePlayers()) {
           if (IPUtils.toIPAddress(onlinePlayer.getAddress()).equals(ip)) {
-            onlinePlayer.kick(kickMessage.toString());
+            onlinePlayer.kick(kickMessage);
           }
         }
       });

common/src/main/java/me/confuser/banmanager/common/commands/BanIpRangeCommand.java

@@ -82,7 +82,7 @@ public boolean onCommand(final CommonSender sender, CommandParser parser) {
 
         for (CommonPlayer onlinePlayer : getPlugin().getServer().getOnlinePlayers()) {
           if (ban.inRange(IPUtils.toIPAddress(onlinePlayer.getAddress()))) {
-            onlinePlayer.kick(kickMessage.toString());
+            onlinePlayer.kick(kickMessage);
           }
         }
       });