From 5a57627808625d89956533074dc7f5ee799b2e66 Mon Sep 17 00:00:00 2001 From: James Mortemore Date: Sat, 4 Apr 2026 14:25:17 +0100 Subject: [PATCH] docs: add localisation documentation for BanManager i18n Document the new multi-language message system including the messages/ directory structure, locale naming conventions, cascading fallback, per-player locale resolution, and the new locale config settings. --- .../banmanager/configuration/config-yml.mdx | 15 ++++++ .../banmanager/configuration/messages-yml.mdx | 48 +++++++++++++++---- content/docs/banmanager/faq.mdx | 2 +- 3 files changed, 56 insertions(+), 9 deletions(-) diff --git a/content/docs/banmanager/configuration/config-yml.mdx b/content/docs/banmanager/configuration/config-yml.mdx index eb39e65e..cbb1bb62 100644 --- a/content/docs/banmanager/configuration/config-yml.mdx +++ b/content/docs/banmanager/configuration/config-yml.mdx @@ -349,4 +349,19 @@ The main configuration file for BanManager. ``` --- + - ###### `locale` + Controls localisation settings for BanManager. See the [messages documentation](/docs/banmanager/configuration/messages-yml) for details on adding translations. + - ###### `default` + The server-wide default locale used when resolving messages. This should match the name of a message file in the `messages/` directory, e.g. `en` will load `messages/messages_en.yml`. Defaults to `en`. + - ###### `perPlayer` + When enabled, messages are resolved using each player's Minecraft client language setting. BanManager will automatically detect the player's locale and resolve messages in their language if a matching translation file exists, falling back to the default locale otherwise. The player's locale is also stored in the database so that join-deny messages (e.g. ban screens) can be shown in the correct language. Defaults to `true`. + + **Example** + ```yml + locale: + default: en + perPlayer: true + ``` + --- + diff --git a/content/docs/banmanager/configuration/messages-yml.mdx b/content/docs/banmanager/configuration/messages-yml.mdx index 89dcaf73..73916f9e 100644 --- a/content/docs/banmanager/configuration/messages-yml.mdx +++ b/content/docs/banmanager/configuration/messages-yml.mdx @@ -1,22 +1,54 @@ --- layout: 'docs' -title: 'messages.yml' -navTitle: 'messages.yml' +title: 'Messages' +navTitle: 'Messages' category: 'Configuration' -description: 'All messages can be fully customised, supporting JSON, colour codes and more!' +description: 'All messages can be fully customised, with multi-language support, JSON, colour codes and more!' --- Defines BanManager's messages throughout the plugin. Messages support [JSON](https://minecraft.fandom.com/wiki/Raw_JSON_text_format), [Minecraft colour codes](https://gamedb.gg/games/minecraft/bukkit-color-codes/) and RGB hex colors e.g. `&#ff5500` using the `&` delimiter. Use `\n` for new lines. Text wrapped inside square brackets i.e. `[player]` are tokens which will be replaced with their corresponding value. Set values to an empty string, i.e. `''` if you do not wish the message to display. +### Localisation + +BanManager supports multi-language messages. Messages are stored in the `messages/` directory with one file per locale, named `messages_.yml` (e.g. `messages_en.yml`, `messages_de.yml`, `messages_zh.yml`). + | Platform | Location | | -------- | -------- | -| CraftBukkit/Spigot/Paper | `/plugins/BanManager/messages.yml` | -| BungeeCord | `/plugins/BanManager/messages.yml` | -| Fabric | `/config/banmanager/messages.yml` | -| Sponge | `/config/banmanager/messages.yml` | -| Velocity | `/plugins/BanManager/messages.yml` | +| CraftBukkit/Spigot/Paper | `/plugins/BanManager/messages/` | +| BungeeCord | `/plugins/BanManager/messages/` | +| Fabric | `/config/banmanager/messages/` | +| Sponge | `/config/banmanager/messages/` | +| Velocity | `/plugins/BanManager/messages/` | + +On first run, BanManager will create the `messages/` directory and copy the default `messages_en.yml` file. The legacy `messages.yml` file is still supported as an overlay — any messages defined in it will override the corresponding locale file for the default locale. + +#### Adding a language + +1. Copy `messages/messages_en.yml` to a new file, e.g. `messages/messages_de.yml` for German +2. Translate the messages in the new file +3. Run `/bmreload` to load the new locale + +You do not need to translate every message. Missing keys will fall back through a cascading chain: + +1. **Exact locale** — e.g. `zh_tw` +2. **Base language** — e.g. `zh` +3. **Default locale** — as set in [config.yml](/docs/banmanager/configuration/config-yml#locale) + +#### Locale naming + +Use two-letter language codes by default (e.g. `en`, `de`, `fr`, `zh`). For regional variants, use the format `_` (e.g. `zh_tw`, `pt_br`, `en_us`). Locale names are case-insensitive — `en_GB` is normalised to `en_gb` internally. + +#### Per-player locale + +When [`locale.perPlayer`](/docs/banmanager/configuration/config-yml#locale) is enabled (the default), each player sees messages in their Minecraft client's language if a matching translation is available. This includes kick messages and ban deny screens. The player's locale is stored in the database so that join-deny messages can be displayed in the correct language even before the player fully connects. + +When disabled, all players see messages in the server's default locale. + +#### Startup diagnostics + +On startup, BanManager logs the number of loaded locales and reports any missing message keys in non-default locales. This helps identify untranslated messages. ### PlaceholderAPI Support (Bukkit) On Bukkit-based servers with [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) installed, you can use PlaceholderAPI tokens directly in messages. For example: `%player_name%`, `%server_online%`, etc. diff --git a/content/docs/banmanager/faq.mdx b/content/docs/banmanager/faq.mdx index 0b8a1280..3cc512d3 100644 --- a/content/docs/banmanager/faq.mdx +++ b/content/docs/banmanager/faq.mdx @@ -20,7 +20,7 @@ This can be caused by a number of issues, refer to the common [Storage Errors](# [v2.x versions](https://dev.bukkit.org/projects/ban-management/files?filter-game-version=2020709689%3A6378) of BanManager have been reported as compatible. At a mimimum you will require [v2.2](https://dev.bukkit.org/projects/ban-management/files/675342), please ensure `useSyncChat` is enabled in the config. Please note the following: documentation and guides are for recent BanManager versions only, there may be bugs, cross-server sync is not supported and older versions of BanManager are name based, not UUID meaning a change of name will evade bans for online-mode servers. ### How can I add new lines to the player denied screen when a banned player tries to join? -Use `\n` within the message in the messages.yml wherever you'd like a new line to start. For example: +Use `\n` within the message in your locale file (e.g. `messages/messages_en.yml`) wherever you'd like a new line to start. For example: ```yml disallowed: '&6Banned on Frostcast\n[reason]'