Skip to main content

​
Translation System

The RPG Leveling plugin supports full localization with per-player languages. Each player picks their own language from the in-game Settings tab and the HUD, notifications, level-up titles, zone warnings, kill messages and /lvl info follow that choice. Server-side messages (logs, console output, broadcasts without a specific recipient) use the server default language.

​
How it works

​
The languages/ folder

All translation files live in: 
mods/Zuxaw_RPGLeveling/languages/
Each language is one file named: 
MessagesLanguageMapping_<lang>.json
<lang> is a lowercase identifier (no spaces) - for example english, french, spanish, de, pt_br. The exact code is what players store on their character; pick something simple and stable. Examples: 
mods/Zuxaw_RPGLeveling/languages/
├── MessagesLanguageMapping_english.json   ← always created by the plugin
├── MessagesLanguageMapping_french.json
└── MessagesLanguageMapping_spanish.json
Migration from older versions - If you upgrade from a version that used mods/Zuxaw_RPGLeveling/MessagesLanguageMapping.json (single-file translation), the file is moved automatically into languages/ on first start. If your old file is not English, rename it to the correct suffix (example: MessagesLanguageMapping_french.json) and set language.display_name (example: Français), otherwise it will appear as English in the in-game picker.

​
Auto-discovery

On startup the plugin scans languages/ for any file matching MessagesLanguageMapping_*.json and loads it. There is no central registry to edit - drop a file in, restart, and the language appears in the in-game picker. If MessagesLanguageMapping_english.json is missing, the plugin creates it from the in-code defaults so English is always available as a fallback.

​
Self-localizing display names

Each bundle declares its own display name under the language section: 
{
  "language": {
    "display_name": "Français"
  }
}
The in-game Settings → Language list reads language.display_name for each detected file. There is no central translation table to keep in sync - the file describes itself. If language.display_name is missing, the picker falls back to a capitalized version of the language code (french → French).

​
Keeping translations up to date

Every time the server starts (and on /lvl reload), language files are updated to include new text entries added by plugin updates while keeping your existing translated text:
  • New entries are added with English text as placeholders.
  • Old unused entries are removed.
  • Your translated lines stay untouched.
  • A short per-file report is printed in console.
This keeps each language file clean and easy to maintain after updates.

​
Player-aware message routing

Every player has a Language field on their PlayerLevelData. When the plugin needs to display text to a specific player, it resolves the bundle in this order:
  1. The player’s chosen language (PlayerLevelData.Language).
  2. The server’s DefaultLanguage (from RPGLevelingConfig.json).
  3. english (always present).
  4. In-code defaults (last-resort fallback so the game never shows a raw key).
This means a missing key in a translation file silently falls through to English instead of breaking the GUI.

​
Setting language from another mod

Server mods can change a player’s RPG Leveling language in code using the same bundle codes as in languages/. See API - Player language for dependencies, methods (setPlayerLanguage, setPlayerLanguageByUsername, etc.), and examples.

​
Server default language

The server-wide default lives in mods/Zuxaw_RPGLeveling/RPGLevelingConfig.json: 
{
  "DefaultLanguage": "english"
}
It is used for:
  • New players who have not opened the picker yet.
  • Server console output and log lines.
  • Broadcasts that do not target a specific player (e.g. global XP boost titles still use each recipient’s own language; only truly recipient-less messages fall back to the default).
Set it to any language code you have in languages/ (for example "french" for a fully French-speaking server).

​
Picking a language in-game

  1. Open the Stats GUI (/lvl gui, default key, or Open RPG GUI binding).
  2. Click the Settings tab in the sidebar.
  3. Scroll to Language.
  4. Click Switch next to the language you want.
The choice is saved immediately on your character and replicated to the database. The GUI re-renders in the new language and the HUD / next notification follow.

​
Adding a new translation

  1. Make sure the server has been started at least once so languages/MessagesLanguageMapping_english.json exists.
  2. Copy that file to languages/MessagesLanguageMapping_<your_lang>.json (e.g. MessagesLanguageMapping_french.json).
  3. Open your copy and translate the values only - never change the keys.
  4. Set "language"."display_name" to what should appear in the picker (e.g. "Français").
  5. Restart the server (or /lvl reload).
  6. Open Settings → Language in-game; your file should appear in the list.
You do not need to touch the English file or any other config - adding a language is a pure file drop.

​
What to translate, what to keep

  • ✅ Translate the string values.
  • ❌ Do not rename the keys (e.g. level_up_title).
  • ❌ Do not change placeholders like {0}, {1} - they are replaced with player names, levels, XP values, etc. by the plugin. The order of placeholders must stay the same; you can move them around in the sentence as long as {0} still means “first argument”.
  • ❌ Do not translate plugin-internal identifiers (UUIDs, stat keys, brand name “RPG Leveling”).

​
Length and formatting

  • The HUD and toast titles have limited width. If a translation overflows, prefer shorter wording over very long sentences.
  • Numeric formatting (+1, 50%, 100/200, Level 12) stays universal and is composed in code, so you usually translate the surrounding label, not the number.

​
Testing

After editing a file:
  • Run /lvl reload to pick up changes without restarting.
  • Switch to your language in Settings → Language.
  • Check: HUD, level-up title, an XP gain toast, the kill message, /lvl info, the Stats GUI Settings tab.

​
Smart merge report (console)

On startup or /lvl reload, each language file produces a short report: 
=============================================================
MESSAGES FILE MERGE REPORT - MessagesLanguageMapping_french.json
=============================================================
✅ Added 2 new message(s) (defaulted to English)
❌ Removed 1 obsolete message(s)
💾 Preserved 374 user translation(s)
=============================================================
Use it after each plugin update to spot newly added keys that need translation.

​
Troubleshooting

My language file is not in the picker.
  • File name must match MessagesLanguageMapping_<lowercase_code>.json exactly.
  • It must be inside mods/Zuxaw_RPGLeveling/languages/ (not in the parent folder).
  • Run /lvl reload or restart the server; the picker reads the registry on open.
Some messages are still English.
  • Open your file and search for keys flagged in the merge report - they are probably new and still default to English.
  • Missing keys fall back to English by design; this prevents broken GUIs after plugin updates.
My old MessagesLanguageMapping.json disappeared.
  • It was moved to languages/MessagesLanguageMapping_english.json by the upgrade migration. Your translations are preserved there.
Reset a translation file.
  • Delete languages/MessagesLanguageMapping_<lang>.json and restart. For English, the plugin recreates it from defaults; for any other language you keep the file you authored.

​
Translation quality policy

This project does not rely on automatic AI translation quality for official language files.
  • We prefer translations made and reviewed by real players/community members.
  • If you are not sure about a language, leave it in English until a native speaker provides a proper version.

​
Sharing translations

If you create a translation, please share it on our Discord - it can be added to the next release as an officially bundled language file.

​
See also