# Languages and Messages

## Language and Messages

BuildersWand supports multiple languages and provides extensive customization of all user-facing messages. This system allows you to tailor the plugin's communication to match your server's style and language preferences.

### Language Files

The plugin includes language files in the `lang/` directory:

* `en.yml` - English (default)
* `de.yml` - German
* `es.yml` - Spanish

### Setting the Language

In `config.yml`, set your preferred language:

```yaml
general:
  language: "en"  # Options: en, de, es
```

### Message Categories

All messages are organized into logical categories:

#### Command Messages

```yaml
messages:
  reload: "&aThe configuration has been reloaded successfully."
  playerNotFound: "&cPlayer not found!"
  noPermissions: "&cYou don't have permission to use this command!"
  wandNotFound: "&cThe wand could not be found."
  invalidTier: "&cInvalid tier specified."
```

#### Usage Restriction Messages

```yaml
  dailyLimitReached: "&cYou have reached your daily usage limit!"
  sessionLimitReached: "&cYou have reached your session usage limit!"
  rateLimitReached: "&cYou are using the wand too quickly!"
  worldDisabled: "&cWands are disabled in this world!"
  creativeOnly: "&cWands can only be used in creative mode!"
  survivalOnly: "&cWands can only be used in survival mode!"
```

#### Permission Messages

```yaml
  noWandPermission: "&cYou don't have permission to use this wand!"
  blockBlacklisted: "&cThis block type is blacklisted!"
  blockPlaceOnly: "&cThis block can only be placed, not broken!" # {block} provides mentioned material name
  blockBreakOnly: "&cThis block can only be broken, not placed!" # {block} provides mentioned material name
  noBlockPermission: "&cYou don't have permission to use this block type!" # {block} provides mentioned material name
  materialLimitReached: "&cYou have reached the limit for this material!"
```

#### Feature Messages

```yaml
  undoDisabled: "&cThe undo feature is disabled!"
  noUndoAvailable: "&cNo actions available to undo!"
  mustBeHoldingWand: "&cYou must be holding a BuildersWand!"
  modeChanged: "&aWand mode changed to {mode}."
  distanceChanged: "&aWand distance changed to {distance}."
  particlesEnabled: "&aParticles enabled."
  particlesDisabled: "&cParticles disabled."
```

#### GUI Messages

```yaml
  mainGuiTitle: "&8BuildersWand Settings"
  modeButton: "&6Mode"
  modeButtonLore: "&7Click to cycle through available modes"
  distanceButton: "&bDistance"
  distanceButtonLore: "&7Current: &e{distance}&7/&e{max_range}&7 blocks"
  particlesButton: "&dParticles"
  particlesButtonLore: "&7Toggle particle effects"
  storageButton: "&aStorage"
  storageButtonLore: "&7Open wand storage"
  enabled: "&aEnabled"
  disabled: "&cDisabled"
```

#### Statistics Messages

```yaml
  statsHeader: "&eStatistics:"
  statsTotalPlayers: "&7Total players: &e{count}"
  statsTotalWands: "&7Total wands: &e{count}"
  statsTopPlayers: "&eTop Players:"
  statsPlayerEntry: "&7{player}: &e{blocks} blocks (&a{placed} placed&7/&c{broken} broken)"
  statsWandUsage: "&eWand Usage:"
  statsWandEntry: "&7{wand}: &e{blocks} blocks (&a{placed} placed&7/&c{broken} broken)"
  statsCleared: "&aStatistics cleared."
```

### Color Codes

All messages support Minecraft color codes:

**Colors:**

* `&0` - Black
* `&1` - Dark Blue
* `&2` - Dark Green
* `&3` - Dark Aqua
* `&4` - Dark Red
* `&5` - Dark Purple
* `&6` - Gold
* `&7` - Gray
* `&8` - Dark Gray
* `&9` - Blue
* `&a` - Green
* `&b` - Aqua
* `&c` - Red
* `&d` - Light Purple
* `&e` - Yellow
* `&f` - White

**Formatting:**

* `&l` - Bold
* `&n` - Underline
* `&o` - Italic
* `&k` - Obfuscated
* `&m` - Strikethrough
* `&r` - Reset

### Placeholders

Many messages support placeholders that are automatically replaced:

**General Placeholders:**

* `{player}` - Player name
* `{count}` - Number of blocks
* `{mode}` - Current wand mode
* `{distance}` - Current wand distance
* `{max_range}` - Maximum wand range
* `{durability}` - Current durability
* `{wand}` - Wand name
* `{placed}` - Blocks placed
* `{broken}` - Blocks broken

**Example Usage:**

```yaml
modeChanged: "&aWand mode changed to {mode}."
distanceChanged: "&aWand distance changed to {distance}."
blocksPlaced: "&aBlocks placed: &e{count}"
```

### Customizing Messages

#### Modifying Existing Messages

To customize messages for your server:

1. **Backup the original file**
2. **Edit the message text** - Change the text after the colon
3. **Keep the structure** - Don't change the message keys
4. **Test your changes** - Use `/bw reload` to apply changes

### Message Prefix

The message prefix is configured in `config.yml`:

```yaml
ui:
  messages:
    prefix: "&8[&bBuildersWand&8]"
```

This prefix is automatically added to most messages. You can customize it to match your server's style:

**Examples:**

* `"&8[&bBuildersWand&8]"` - Default style
* `"&7[&aBW&7]"` - Short and clean
* `"&6[&lWand&6]"` - Bold and golden
* `""` - No prefix (empty string)

### Action Bar Messages

Some messages appear in the action bar (if your server version is supported by the Adventure API):

```yaml
wandMode: "&bMode: &e{mode}"
wandDurability: "&dDurability: &e{durability}"
```

These messages are shown when:

* `show-wand-mode: true` in config.yml
* `show-durability: true` in config.yml
* Player is not in creative mode

### Sound Messages

Sound effects are configured in `config.yml` but can be referenced in messages:

```yaml
ui:
  sounds:
    wand-break-sound: "ENTITY_ITEM_BREAK"
    block-place-sound: "BLOCK_STONE_PLACE"
    mode-change-sound: "ENTITY_EXPERIENCE_ORB_PICKUP"
```

### Help Messages

Command help messages are also customizable:

```yaml
helpHeader: "&b&eAvailable commands:"
helpReload: "&r&e/bw reload &7- Reloads the configuration."
helpGiveSelf: "&r&e/bw give &7- Gives yourself a wand."
helpGiveOther: "&r&e/bw give <player> <tier> &7- Gives a wand to another player."
helpUndo: "&r&e/bw undo &7- Undo your last wand action."
```

### Troubleshooting

**Messages not updating:**

* Use `/bw reload` after making changes
* Check YAML syntax (proper indentation)
* Verify message keys are correct

**Color codes not working:**

* Ensure you're using `&` not `§`
* Check that the color code is valid
* Make sure the message is being sent to a player (not console)

**Placeholders not replacing:**

* Verify placeholder syntax: `{placeholder}`
* Check that the placeholder name is correct
* Ensure the value is available when the message is sent

The language system is designed to be flexible and extensible, allowing you to create the perfect user experience for your server's community.
