🌐Messages & Localization

Complete guide to customizing messages and adding multi-language support.

Overview

BlackMarket supports two message systems:

Legacy Mode: Single messages.yml file
Localization Mode: Multiple language files in lang/ folder

Configuration

Enable/Disable Localization

# config.yml
messages:
  # Use MiniMessage for modern formatting
  use-minimessage: true
  
  # Enable localization system
  localization: false  # true = use lang/ files
  
  # Active language (only if localization enabled)
  lang: "EN_US"  # Filename without .yml

Message Formatting

MiniMessage Format (Recommended)

When use-minimessage: true:

# Simple colors
message: "<red>Error!</red>"
message: "<green>Success!</green>"

# Gradients
message: "<gradient:#FFD700:#FFA500>BlackMarket</gradient>"

# Multiple effects
message: "<bold><gradient:#FF0000:#0000FF>Title</gradient></bold>"

# Rainbow
message: "<rainbow>Colorful Text</rainbow>"

# Hover and click events
message: "<hover:show_text:'Click me!'><click:run_command:/shop>Open Shop</click></hover>"

Common Tags:

Colors: <red>, <blue>, <green>, <yellow>, <gold>, <aqua>, <white>, <gray>, <dark_gray>, <black>
Formatting: <bold>, <italic>, <underlined>, <strikethrough>, <obfuscated>
Special: <gradient:#START:#END>, <rainbow>, <reset>

Legacy Color Codes

When use-minimessage: false:

# Colors
message: "&cError!"
message: "&aSuccess!"

# Formatting
message: "&l&bBold Blue"
message: "&o&eItalic Yellow"

# Combined
message: "&6&lBlack&e&lMarket"

Color Codes:

&0-9, a-f - Colors
&l - Bold
&o - Italic
&n - Underline
&m - Strikethrough
&k - Obfuscated
&r - Reset

Note: Both formats work together when MiniMessage is enabled!

Legacy Mode (messages.yml)

File Location

plugins/BlackMarket/messages.yml

Structure

# Prefix used in all messages
prefix: "<gradient:#FFD700:#FFA500><bold>BlackMarket</bold></gradient> <dark_gray>»</dark_gray>"

# General messages
no-permission: "%prefix% <red>You don't have permission.</red>"
player-only: "%prefix% <red>Only players can use this.</red>"

# Purchase messages
purchase:
  success: "%prefix% <green>Purchase successful!</green>"
  failed: "%prefix% <red>Transaction failed.</red>"

# Lists
help:
  - ""
  - "<gold>Help Menu</gold>"
  - "<gray>Command 1"
  - "<gray>Command 2"
  - ""

Using the Prefix

The %prefix% placeholder automatically includes your configured prefix:

prefix: "[Shop] »"

# This message:
no-permission: "%prefix% <red>No permission!</red>"

# Displays as:
# [Shop] » No permission!

Localization Mode (lang/ files)

Enable Localization

# config.yml
messages:
  localization: true
  lang: "EN_US"  # Without .yml extension

File Location

plugins/BlackMarket/lang/EN_US.yml
plugins/BlackMarket/lang/ES_ES.yml
plugins/BlackMarket/lang/FR_FR.yml

Creating Language Files

Copy default language:

cp plugins/BlackMarket/lang/EN_US.yml plugins/BlackMarket/lang/DE_DE.yml

Translate messages:

# DE_DE.yml (German)
prefix: "<gradient:#FFD700:#FFA500><bold>SchwarzMarkt</bold></gradient> <dark_gray>»</dark_gray>"

no-permission: "%prefix% <red>Du hast keine Berechtigung.</red>"

purchase:
  success: "%prefix% <green>Kauf erfolgreich!</green>"
  insufficient-funds: "%prefix% <red>Nicht genug Geld! Benötigt: <yellow>%price%</yellow></red>"

Switch language:

# config.yml
messages:
  lang: "DE_DE"

Reload:

/bma reload messages

Complete Message Reference

General Messages

prefix: "<gradient:#FFD700:#FFA500><bold>BlackMarket</bold></gradient> <dark_gray>»</dark_gray>"

no-permission: "%prefix% <red>You don't have permission to do this.</red>"
player-only: "%prefix% <red>Only players can use this command.</red>"
reload-success: "%prefix% <green>Configuration reloaded successfully!</green>"
market-reset: "%prefix% <yellow>The market has been reset with new items!</yellow>"

Purchase Messages

purchase:
  success: "%prefix% <green>Purchase successful!</green>"
  failed: "%prefix% <red>Transaction failed. Please try again.</red>"
  insufficient-funds: "%prefix% <red>You don't have enough money! Required: <yellow>%price%</yellow></red>"
  out-of-stock: "%prefix% <red>This item is out of stock!</red>"
  already-bought: "%prefix% <red>You have already purchased this item!</red>"
  on-cooldown: "%prefix% <red>This item is on cooldown! Time remaining: <yellow>%time%</yellow></red>"
  expired: "%prefix% <red>This item has expired!</red>"
  no-permission: "%prefix% <red>You don't have permission to buy this item!</red>"

Available Placeholders:

%price% - Item price
%time% - Cooldown remaining
%player% - Player name

Admin Messages

admin:
  reset: "%prefix% <yellow>Market has been forcefully reset!</yellow>"
  player-not-found: "%prefix% <red>Player not found!</red>"
  opened-for-player: "%prefix% <green>Opened market for <yellow>%player%</yellow>.</green>"
  usage: "%prefix% <gray>Usage: /blackmarketadmin <subcommand></gray>"
  usage-open: "%prefix% <red>Usage: /blackmarketadmin open <player></red>"
  unknown-command: "%prefix% <red>Unknown command! Use /bma help for help.</red>"
  debug-toggled: "%prefix% <yellow>Debug mode has been toggled to <gold>%debug_mode%</gold>!</yellow>"

Help Messages

help:
  - ""
  - "<gradient:#FFD700:#FFA500><bold>BlackMarket Help</bold></gradient>"
  - "<gray>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</gray>"
  - "<yellow>/blackmarket</yellow> <gray>- Open the market"
  - "<yellow>/blackmarket help</yellow> <gray>- Show this help"
  - "<yellow>/blackmarket info</yellow> <gray>- Show market info"
  - ""
  - "<gold>Next Reset:</gold> <yellow>%time_until_reset_detailed%</yellow>"
  - "<gray>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</gray>"
  - ""

admin-help:
  - ""
  - "<gradient:#FFD700:#FFA500><bold>BlackMarket Admin Commands</bold></gradient>"
  - "<gray>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</gray>"
  - "<yellow>/bma help</yellow> <gray>- Show all commands"
  - "<yellow>/bma reload</yellow> <gray>- Reload configuration"
  - "<yellow>/bma reset</yellow> <gray>- Force market reset"
  - "<yellow>/bma open <player></yellow> <gray>- Open market for player"
  - "<yellow>/bma info</yellow> <gray>- Show plugin info"
  - "<yellow>/bma debug</yellow> <gray>- Toggle debug mode"
  - "<gray>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</gray>"
  - ""

Info Messages

info-player:
  - ""
  - "<gradient:#FFD700:#FFA500><bold>BlackMarket Info</bold></gradient>"
  - "<gray>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</gray>"
  - "<gold>Market Type:</gold> <yellow>%market_type%</yellow>"
  - "<gold>Available Items:</gold> <yellow>%items_count%</yellow>"
  - "<gold>Next Reset:</gold> <yellow>%time_until_reset_detailed%</yellow>"
  - "<gray>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</gray>"
  - ""

admin-info:
  - ""
  - "<gradient:#FFD700:#FFA500><bold>BlackMarket Admin Info</bold></gradient>"
  - "<gray>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</gray>"
  - "<gold>Version:</gold> <yellow>%version%</yellow>"
  - "<gold>Server:</gold> <yellow>%server_type%</yellow>"
  - "<gold>Market Type:</gold> <yellow>%market_type%</yellow>"
  - "<gold>Database:</gold> <yellow>%database_type%</yellow>"
  - "<gold>Economy:</gold> <yellow>%economy_provider%</yellow>"
  - "<gold>Online Players:</gold> <yellow>%online_players%</yellow>"
  - "<gold>Language:</gold> <yellow>%current_language%</yellow>"
  - "<gray>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</gray>"
  - ""

debug-info:
  - ""
  - "<gradient:#FFD700:#FFA500><bold>BlackMarket Debug Info</bold></gradient>"
  - "<gray>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</gray>"
  - "<gold>Debug Mode:</gold> <yellow>%debug_mode%</yellow>"
  - "<gold>Folia Support:</gold> <yellow>%folia_enabled%</yellow>"
  - "<gold>Reset Interval:</gold> <yellow>%reset_interval%</yellow>"
  - "<gold>Items Per Reset:</gold> <yellow>%items_per_reset%</yellow>"
  - "<gold>Pagination:</gold> <yellow>%pagination_enabled%</yellow>"
  - "<gold>Categories:</gold> <yellow>%categories_enabled%</yellow>"
  - "<gold>MiniMessage:</gold> <yellow>%minimessage_enabled%</yellow>"
  - "<gold>Localization:</gold> <yellow>%localization_enabled%</yellow>"
  - "<gold>Current Language:</gold> <yellow>%current_language%</yellow>"
  - "<gray>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</gray>"
  - ""

Error Messages

error:
  database-connection: "%prefix% <red>Failed to connect to database!</red>"
  economy-missing: "%prefix% <red>No economy plugin found!</red>"
  config-error: "%prefix% <red>Error in configuration: %error%</red>"
  command-error: "%prefix% <red>An error occurred while executing this command.</red>"

Action Bar Messages

actionbar:
  purchase-success: "<green>✓</green> <gray>Purchase successful!</gray>"
  purchase-failed: "<red>✘</red> <gray>Purchase failed!</gray>"
  insufficient-funds: "<red>✘</red> <gray>Not enough money!</gray>"
  page-changed: "<yellow>→</yellow> <gray>Page %page%/%total_pages%</gray>"
  category-changed: "<yellow>→</yellow> <gray>Category: %category%</gray>"

GUI Messages

gui:
  loading: "<gray>Loading market...</gray>"
  no-items: "<red>No items available!</red>"
  market-closed: "<red>The market is currently closed!</red>"

Creating Custom Languages

Example: Spanish (ES_ES.yml)

# Spanish Translation
prefix: "<gradient:#FFD700:#FFA500><bold>MercadoNegro</bold></gradient> <dark_gray>»</dark_gray>"

no-permission: "%prefix% <red>No tienes permiso para hacer esto.</red>"
player-only: "%prefix% <red>Solo los jugadores pueden usar este comando.</red>"
reload-success: "%prefix% <green>¡Configuración recargada exitosamente!</green>"
market-reset: "%prefix% <yellow>¡El mercado ha sido reiniciado con nuevos artículos!</yellow>"

purchase:
  success: "%prefix% <green>¡Compra exitosa!</green>"
  failed: "%prefix% <red>Transacción fallida. Por favor intenta de nuevo.</red>"
  insufficient-funds: "%prefix% <red>¡No tienes suficiente dinero! Requerido: <yellow>%price%</yellow></red>"
  out-of-stock: "%prefix% <red>¡Este artículo está agotado!</red>"
  already-bought: "%prefix% <red>¡Ya has comprado este artículo!</red>"
  on-cooldown: "%prefix% <red>¡Este artículo está en tiempo de espera! Tiempo restante: <yellow>%time%</yellow></red>"
  expired: "%prefix% <red>¡Este artículo ha expirado!</red>"

help:
  - ""
  - "<gradient:#FFD700:#FFA500><bold>Ayuda de MercadoNegro</bold></gradient>"
  - "<gray>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</gray>"
  - "<yellow>/mercadonegro</yellow> <gray>- Abrir el mercado"
  - "<yellow>/mercadonegro ayuda</yellow> <gray>- Mostrar esta ayuda"
  - "<yellow>/mercadonegro info</yellow> <gray>- Mostrar información del mercado"
  - ""
  - "<gold>Próximo Reinicio:</gold> <yellow>%time_until_reset_detailed%</yellow>"
  - "<gray>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</gray>"
  - ""

Example: French (FR_FR.yml)

# French Translation
prefix: "<gradient:#FFD700:#FFA500><bold>MarchéNoir</bold></gradient> <dark_gray>»</dark_gray>"

no-permission: "%prefix% <red>Vous n'avez pas la permission de faire cela.</red>"
player-only: "%prefix% <red>Seuls les joueurs peuvent utiliser cette commande.</red>"
reload-success: "%prefix% <green>Configuration rechargée avec succès!</green>"
market-reset: "%prefix% <yellow>Le marché a été réinitialisé avec de nouveaux articles!</yellow>"

purchase:
  success: "%prefix% <green>Achat réussi!</green>"
  failed: "%prefix% <red>Transaction échouée. Veuillez réessayer.</red>"
  insufficient-funds: "%prefix% <red>Vous n'avez pas assez d'argent! Requis: <yellow>%price%</yellow></red>"
  out-of-stock: "%prefix% <red>Cet article est en rupture de stock!</red>"

help:
  - ""
  - "<gradient:#FFD700:#FFA500><bold>Aide MarchéNoir</bold></gradient>"
  - "<gray>━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</gray>"
  - "<yellow>/marchenoir</yellow> <gray>- Ouvrir le marché"
  - "<yellow>/marchenoir aide</yellow> <gray>- Afficher cette aide"
  - ""

Best Practices

1. Consistent Formatting

Keep consistent styling throughout:

# Good - Consistent
prefix: "<gold>[Shop]</gold> <gray>»</gray>"
success: "%prefix% <green>Success!</green>"
error: "%prefix% <red>Error!</red>"

# Bad - Inconsistent
prefix: "&6[Shop] &7»"
success: "<green>Success!</green> %prefix%"
error: "&cError! [Shop]"

2. Use Placeholders

Always use placeholders for dynamic content:

# Good
insufficient-funds: "%prefix% <red>Need %price% but have %balance%</red>"

# Bad
insufficient-funds: "%prefix% <red>Not enough money!</red>"

3. Clear Messages

Make messages clear and actionable:

# Good
out-of-stock: "%prefix% <red>This item is sold out! Try again after the next reset.</red>"

# Bad
out-of-stock: "%prefix% <red>Error 404</red>"

4. Organize by Category

Group related messages:

# Purchase messages
purchase:
  success: "..."
  failed: "..."
  
# Admin messages
admin:
  reset: "..."
  reload: "..."

Testing Messages

1. Reload Messages

/bma reload messages

2. Trigger Messages

Test each message type:

Buy an item → Purchase messages
Run admin commands → Admin messages
View help → Help messages

3. Check Formatting

Verify colors and formatting appear correctly in-game.

Common Issues

Issue 1: Colors Not Showing

Problem: Messages appear without colors

Solution: Check MiniMessage setting

# config.yml
messages:
  use-minimessage: true  # Enable for <red> tags

Issue 2: Prefix Not Working

Problem: %prefix% shows literally

Solution: Ensure prefix is defined

prefix: "<gold>[Shop]</gold>"
no-permission: "%prefix% <red>No permission</red>"

Issue 3: Language File Not Loading

Problem: Messages don't change after switching language

Solution:

Check filename matches exactly (case-sensitive)
Verify file is in lang/ folder
Reload: /bma reload messages

# config.yml - Must match filename exactly
messages:
  lang: "EN_US"  # File: lang/EN_US.yml

Issue 4: Quotes in YAML

Problem: YAML errors with special characters

Solution: Quote strings with %:

# Wrong
message: %prefix% <red>Error</red>

# Correct
message: "%prefix% <red>Error</red>"

Multi-Language Setup Example

Step-by-Step

1. Enable localization:

# config.yml
messages:
  localization: true
  lang: "EN_US"

2. Create language files:

plugins/BlackMarket/lang/
├── EN_US.yml  # English (default)
├── ES_ES.yml  # Spanish
├── FR_FR.yml  # French
└── DE_DE.yml  # German

3. Configure per-player (with permission plugin):

# Allow players to choose language
# Use with plugin like ChatControl or custom system

4. Switch server language:

# For Spanish server
messages:
  lang: "ES_ES"

5. Reload:

/bma reload messages

Advanced: Unicode Characters

Symbols

prefix: "🛒 <gold>Shop</gold> »"
success: "✓ <green>Success!</green>"
error: "✘ <red>Error!</red>"
info: "ℹ <blue>Information</blue>"

Emojis

purchase:
  success: "💰 <green>Purchase successful!</green>"
  failed: "❌ <red>Purchase failed!</red>"
  
market-reset: "🔄 <yellow>Market refreshed!</yellow>"

Box Drawing

help:
  - "╔═══════════════════╗"
  - "║   BlackMarket     ║"
  - "╠═══════════════════╣"
  - "║ /shop - Open      ║"
  - "╚═══════════════════╝"

Message Validation

Checklist

[ ] All placeholders are correct
[ ] Color codes work
[ ] Quotes around messages with %
[ ] No YAML syntax errors
[ ] Tested in-game
[ ] Consistent formatting
[ ] Clear and actionable

Validation Tool

Use YAML Lint to check syntax.

Next Steps

PreviousGUI Customization NextDatabase

Last updated 15 days ago

hashtagOverview

hashtagConfiguration

hashtagEnable/Disable Localization

hashtagMessage Formatting

hashtagMiniMessage Format (Recommended)

hashtagLegacy Color Codes

hashtagLegacy Mode (messages.yml)

hashtagFile Location

hashtagStructure

hashtagUsing the Prefix

hashtagLocalization Mode (lang/ files)

hashtagEnable Localization

hashtagFile Location

hashtagCreating Language Files

hashtagComplete Message Reference

hashtagGeneral Messages

hashtagPurchase Messages

hashtagAdmin Messages

hashtagHelp Messages

hashtagInfo Messages

hashtagError Messages

hashtagAction Bar Messages

hashtagGUI Messages

hashtagCreating Custom Languages

hashtagExample: Spanish (ES_ES.yml)

hashtagExample: French (FR_FR.yml)

hashtagBest Practices

hashtag1. Consistent Formatting

hashtag2. Use Placeholders

hashtag3. Clear Messages

hashtag4. Organize by Category

hashtagTesting Messages

hashtag1. Reload Messages

hashtag2. Trigger Messages

hashtag3. Check Formatting

hashtagCommon Issues

hashtagIssue 1: Colors Not Showing

hashtagIssue 2: Prefix Not Working

hashtagIssue 3: Language File Not Loading

hashtagIssue 4: Quotes in YAML

hashtagMulti-Language Setup Example

hashtagStep-by-Step

hashtagAdvanced: Unicode Characters

hashtagSymbols

hashtagEmojis

hashtagBox Drawing

hashtagMessage Validation

hashtagChecklist

hashtagValidation Tool

hashtagNext Steps

Overview

Configuration

Enable/Disable Localization

Message Formatting

MiniMessage Format (Recommended)

Legacy Color Codes

Legacy Mode (messages.yml)

File Location

Structure

Using the Prefix

Localization Mode (lang/ files)

Enable Localization

File Location

Creating Language Files

Complete Message Reference

General Messages

Purchase Messages

Admin Messages

Help Messages

Info Messages

Error Messages

Action Bar Messages

GUI Messages

Creating Custom Languages

Example: Spanish (ES_ES.yml)

Example: French (FR_FR.yml)

Best Practices

1. Consistent Formatting

2. Use Placeholders

3. Clear Messages

4. Organize by Category

Testing Messages

1. Reload Messages

2. Trigger Messages

3. Check Formatting

Common Issues

Issue 1: Colors Not Showing

Issue 2: Prefix Not Working

Issue 3: Language File Not Loading

Issue 4: Quotes in YAML

Multi-Language Setup Example

Step-by-Step

Advanced: Unicode Characters

Symbols

Emojis

Box Drawing

Message Validation

Checklist

Validation Tool

Next Steps