localization

DialogMaster 3.0 features a high-performance, cross-platform localization engine that allows menus to automatically adapt to each player's Minecraft client language or respect custom player preferences.

1. How It Works

Client Language Auto-Detection

When a player opens a menu, DialogMaster automatically detects their Minecraft language from their game client (Player#locale(), e.g. en_us, es_es, de_de, fr_fr, zh_cn, ar_sa).

Player Language Preference

Players can set their own preferred language override using /ydm lang <code|auto>. The preference is saved directly to the player's persistent data container (PDC).

Hierarchical Fallback Chain

graph TD
    A[Player Custom Preference] -->|If None/Auto| B[Client Reported Locale]
    B -->|If Missing| C[Base Language Dialect e.g. es_mx -> es_es]
    C -->|If Missing| D[Server Default Locale in config.yml]
    D -->|If Missing| E[Raw Translation Key]

2. Translation Tags & Syntax

You can use translation tags in any text field across all menus: menu titles, body text, item previews, button labels, item lore, tooltips, action commands, and broadcast messages.

Supported Tag Formats

• <tr:key> or <lang:key>
• %tr:key% or %lang:key%

Examples

title: "<tr:menus.hub.title>"
body:
  - type: "text"
    content: "<tr:menus.hub.welcome>"
buttons:
  - label: "<tr:menus.hub.survival_btn>"
    tooltip: "<tr:menus.hub.survival_tooltip>"

3. Dynamic Argument Substitution

You can pass arguments and placeholders into translated text by appending :arg=value to the translation tag:

body:
  - type: "text"
    content: "<tr:menus.hub.welcome:player=%player_name%:rank=%vault_group%>"

In your language file (locales/en_us.yml):

menus:
  hub:
    welcome: "<gray>Welcome back, <yellow>%player%</yellow>! Your rank is <green>%rank%</green>.</gray>"

In locales/es_es.yml:

menus:
  hub:
    welcome: "<gray>¡Bienvenido de nuevo, <yellow>%player%</yellow>! Tu rango es <green>%rank%</green>.</gray>"

4. Language Files Storage (plugins/DialogMaster/locales/)

Language dictionaries are stored as standard YAML files in plugins/DialogMaster/locales/:

• locales/en_us.yml (English - US)
• locales/es_es.yml (Spanish - Spain)
• locales/de_de.yml (German)
• locales/fr_fr.yml (French)
• locales/zh_cn.yml (Simplified Chinese)
• locales/ar_sa.yml (Arabic)

Example locales/en_us.yml

menus:
  hub:
    title: "<gold><bold>Game Hub</bold></gold>"
    welcome: "<gray>Welcome to the server!</gray>"
    survival: "<green>Survival SMP</green>"
    skyblock: "<aqua>Skyblock Islands</aqua>"
    store: "<yellow>Server Store</yellow>"

5. Player Commands (/ydm lang)

Command	Permission	Description
/ydm lang	dialogmaster.use	Shows your current language and available server languages.
/ydm lang <locale_code>	dialogmaster.use	Sets your language preference (e.g. /ydm lang es_es).
/ydm lang auto	dialogmaster.use	Re-enables automatic client language detection.

6. In-Game Localization Suite (/ydm editor)

In the visual editor (/ydm editor -> Tools & Locales):

• One-Click Auto-Extraction: Automatically scans all raw strings in your active menu draft (titles, body components, buttons, tooltips, states), extracts them into locales/en_us.yml under menus.<menu_id>.*, and replaces all draft text with <tr:...> tags instantly!
• Language Files Manager: Browse loaded language files, view translation completion percentages, and create new language files (e.g. pt_br.yml, ja_jp.yml) with pre-cloned default keys.
• Key Inspector: Look up any translation key and view/edit its translated value across all installed languages in real time.