# localization

The bot supports multiple languages. Translation files are in `data/locale/`.

***

## Available Languages

| Code | Language | File                  |
| ---- | -------- | --------------------- |
| `en` | English  | `data/locale/en.json` |
| `pl` | Polish   | `data/locale/pl.json` |

***

## Setting Language

In `shared/config.lua`:

```lua
Config.Locale = 'en'  -- or 'pl'
```

***

## Translation Keys

### en.json (English)

```json
{
    "player_not_online": "❌ Player not online",
    "player_not_found": "❌ Player not found",
    "no_permission": "❌ No permission",
    "unknown_command": "❌ Unknown command: %s",
    "usage": "Usage: %s",
    
    "banned": "🔨 Banned **%s** for %s\nBan ID: `%s`\nReason: %s",
    "unbanned": "✅ Unbanned **%s** (Ban ID: %s)",
    "no_active_ban": "❌ No active ban for: %s",
    "ban_found": "🔨 **Ban found:**\nBan ID: %s\nPlayer: %s\nReason: %s\nExpires: %s",
    "no_bans": "📋 No active bans",
    "active_bans": "📋 **Active bans (%d):**\n%s",
    
    "warned": "⚠️ Warned **%s** (%d/5)\nReason: %s",
    "no_warnings": "✅ No warnings for: %s",
    "warnings_list": "⚠️ **Warnings (%d):**\n%s",
    "warning_removed": "✅ Removed warning #%d for %s",
    "warning_not_found": "❌ Warning #%d not found",
    "warnings_cleared": "✅ Cleared warnings for: %s",
    
    "kicked": "👢 Kicked **%s**\nReason: %s",
    "no_players": "📋 No players online",
    "players_online": "📋 **Online (%d):**\n%s",
    
    "announced": "📢 Announced: %s",
    "announce_no_message": "❌ Please provide announcement message",
    
    "chat_warning": "You have been warned: %s (%d/5)",
    "ban_message": "You are banned!\n\nReason: %s\nBan ID: %s\nExpires: %s",
    "checking_ban": "Checking ban status...",
    
    "server_restarting_default": "Server is restarting...",
    "server_restart_announce": "Restart in %d seconds: %s",
    "server_restarting": "🔄 Server restarting in %d seconds",
    
    "server_shutting_down_default": "Server is shutting down...",
    "server_shutdown_announce": "Shutdown in %d seconds: %s",
    "server_shutting_down": "🛑 Server shutting down in %d seconds",
    
    "kickall_default": "All players kicked by admin",
    "kicked_players": "👢 Kicked %d players",
    
    "could_not_get_license": "Could not get license",
    "resource_not_found": "❌ Resource **%s** not found",
    "resource_invalid_action": "❌ Invalid action. Use: start, stop, restart"
}
```

***

## Adding New Language

{% stepper %}
{% step %}

### Create Translation File

Copy `data/locale/en.json` and rename to your language code, for example:

```
data/locale/de.json  (German)
data/locale/fr.json  (French)
data/locale/es.json  (Spanish)
```

{% endstep %}

{% step %}

### Translate Values

Translate all values, keeping the keys and placeholders. Example:

```json
{
    "player_not_online": "❌ Spieler nicht online",
    "banned": "🔨 **%s** für %s gebannt\nBan ID: `%s`\nGrund: %s",
    ...
}
```

{% endstep %}

{% step %}

### Set Language in Config

In `shared/config.lua` change the locale code:

```lua
Config.Locale = 'de'
```

{% endstep %}
{% endstepper %}

***

## Placeholder Reference

| Placeholder | Description      |
| ----------- | ---------------- |
| `%s`        | String (text)    |
| `%d`        | Number (integer) |
| `%f`        | Number (decimal) |

### Examples:

```json
"banned": "Banned %s for %s"
// %s = player name, %s = duration
// Result: "Banned John for 7d"

"warned": "Warned %s (%d/5)"  
// %s = player name, %d = warning count
// Result: "Warned John (3/5)"

"players_online": "Online (%d):\n%s"
// %d = count, %s = player list
// Result: "Online (5):\n[list]"
```

***

## Using Translations in Code

The `L()` function retrieves translations:

```lua
-- Simple translation
local msg = L('player_not_online')
-- Returns: "❌ Player not online"

-- With placeholders
local msg = L('banned', playerName, duration, banId, reason)
-- Returns: "🔨 Banned **John** for 7d\nBan ID: `ABC123`\nReason: Cheating"

-- With numbers
local msg = L('warned', playerName, warnCount, reason)
-- Returns: "⚠️ Warned **John** (3/5)\nReason: VDM"
```

***

{% hint style="info" %}
Best Practices

* Keep placeholders in order — The order of `%s` and `%d` must match the original.
* Test your translations — Make sure all commands work after translating.
* Use UTF-8 encoding — Save files with UTF-8 encoding for special characters.
* Keep emoji — Emoji work in Discord; keep them for visual feedback.
  {% endhint %}