# Lang

## <mark style="color:blue;">Introduction</mark>

The Language configuration file (`lang.json`) contains all messages, embeds, and text strings used by Athena Bot. This file allows you to customize every message the bot sends, translate the bot to other languages, or adjust wording to match your server's style.

***

## <mark style="color:blue;">File Structure</mark>

The language file is organized into several main sections:

```json
{
    lang: {
        // Simple text strings
        unexpected_command_error: "...",
        no_reason_provided: "...",
    },
    embeds: {
        // Embed configurations
        help_default: { ... },
        ping: { ... },
    },
    warnings: {
        // Warning/error messages
        no_permission: "...",
    },
    interaction_names: {
        // Command and option names
    }
}
```

***

## <mark style="color:blue;">Available Placeholders</mark>

### <mark style="color:yellow;">Finding Placeholders</mark>

Each embed and message configuration lists its available placeholders in a comment above it:

```json
// Placeholder: %bot_latency%, %ws_latency%, %api_latency%, %request%
ping: {
    description: "Bot latency: %bot_latency%ms",
}
```

The comment shows which placeholders you can use for that specific message.

***

### <mark style="color:yellow;">Global Placeholders</mark>

These placeholders work in **all** embed configurations throughout the file:

```
%custom_emoji_<number>%     - Custom emojis (e.g., %custom_emoji_28%)
%user%                      - Username
%user_display%              - Display name
%user_id%                   - User ID
%user_mention%              - User mention (@user)
%user_icon%                 - User avatar URL
%user_created%              - Account creation date
%user_created_formatted%    - Formatted creation date
%user_joined%               - Server join date
%user_joined_formatted%     - Formatted join date
%guild%                     - Server name
%guild_id%                  - Server ID
%guild_icon%                - Server icon URL
%random_int_<max_number>%   - Random integer (e.g., %random_int_100%)
%random_string_<length>%    - Random string (e.g., %random_string_8%)
%current_date%              - Current date (YYYY-MM-DD)
%current_time%              - Current time (HH:mm)
%current_time_seconds%      - Current time (HH:mm:ss)
%current_datetime%          - Date and time (YYYY-MM-DD HH:mm)
%current_iso%               - ISO format date (2025-06-02T00:00:00Z)
%bot_user%                  - Bot username
%bot_user_id%               - Bot user ID
%bot_user_mention%          - Bot mention
%bot_user_icon%             - Bot avatar URL
```

{% hint style="info" %}
**Note:** Global placeholders can be used in any message or embed. Specific placeholders (listed above each configuration) only work in their designated messages.
{% endhint %}

***

## <mark style="color:blue;">Configuring Embeds</mark>

### <mark style="color:yellow;">Basic Embed Structure</mark>

Embeds under the `embeds` section support the full Discord embed JSON format. Here's how to configure an embed:

```json
// Placeholder: %bot_latency%, %ws_latency%, %api_latency%, %request%
ping: {
    title: "🏓 Pong!",
    description: "Bot Latency: **%bot_latency%ms**\nWebSocket: **%ws_latency%ms**\nAPI: **%api_latency%ms**",
    color: "#00FF00",
    thumbnail: {
        url: "%bot_user_icon%"
    },
    footer: {
        text: "%guild% - Requested by %user%",
        iconURL: "%guild_icon%"
    },
    defaultTimestamp: true,
}
```

***

### <mark style="color:yellow;">Available Embed Properties</mark>

You can use any Discord embed property in JSON format:

**Basic Properties:**

* `title` - Embed title
* `description` - Main embed text
* `color` - Hex color code (e.g., `"#FF0000"`) or decimal number
* `url` - URL when clicking the title

**Image & Thumbnail:**

* `thumbnail: { url: "..." }` - Small image in top-right
* `image: { url: "..." }` - Large image at bottom

**Author:**

```json
author: {
    name: "Author Name",
    iconURL: "https://...",
    url: "https://..."
}
```

**Footer:**

```json
footer: {
    text: "Footer text",
    iconURL: "https://..."
}
```

**Fields:**

```json
fields: [
    {
        name: "Field Title",
        value: "Field content",
        inline: true
    },
    {
        name: "Another Field",
        value: "More content",
        inline: false
    }
]
```

**Special Properties:**

* `defaultTimestamp: true` - Adds current timestamp to embed
* `guildIcon: true` - Uses server icon in footer

***

### <mark style="color:yellow;">Example: Customizing the Help Embed</mark>

Here's an example of customizing the help command embed:

```json
help_default: {
    title: "📚 %guild% - Command Help",
    description: "Welcome to the help menu, %user%!\n\nUse the buttons below to navigate through different command categories.\n\n**Your Highest Role:** %highest_role%",
    color: "#5865F2",
    thumbnail: {
        url: "%guild_icon%"
    },
    footer: {
        text: "Requested by %user%",
        iconURL: "%user_icon%"
    },
    defaultTimestamp: true,
}
```

***

## <mark style="color:blue;">Simple Text Strings</mark>

Not all messages use embeds. Simple text strings are configured under the `lang` section:

```json
lang: {
    unexpected_command_error: "An **error** occurred while executing __command__ ``%command%``",
    no_reason_provided: "No reason provided",
    modal_placeholder: "Enter a value...",
    left_guild: "User left guild",
}
```

These are plain text strings (with optional Discord markdown formatting) that can include placeholders where specified.

***

## <mark style="color:blue;">Warning Messages</mark>

The `warnings` section contains error and warning messages:

```json
warnings: {
    no_permission: "%user%, you **don't have** __permission__ to use this ``command``",
    cooldown: "%user%, please **wait** ``%time%`` before using this ``command`` again",
}
```

These follow the same format as simple text strings but are used for errors and warnings.

***

## <mark style="color:blue;">Best Practices</mark>

{% hint style="success" %}
**Customization Tips:**

1. **Test changes** - Edit one message at a time and test before making more changes
2. **Keep placeholders** - Don't remove placeholders unless you're sure they're not needed
3. **Maintain formatting** - Keep Discord markdown (`**bold**`, `__underline__`, `` `code` ``) for consistency
4. **Use global placeholders** - Add server branding with `%guild%`, `%guild_icon%`, etc.
5. **Check syntax** - Invalid JSON will cause the bot to fail loading the config
6. **Backup first** - Save a copy of the original file before making changes
   {% endhint %}

{% hint style="warning" %}
**Common Mistakes:**

* Removing required placeholders (e.g., removing `%user%` from a user-specific message)
* Invalid JSON syntax (missing commas, quotes, brackets)
* Using placeholders that don't exist for that message
* Breaking Discord's embed character limits (title: 256, description: 4096, field value: 1024)
  {% endhint %}

***

## <mark style="color:blue;">Example: Complete Custom Embed</mark>

Here's a fully customized embed using multiple properties:

```json
server: {
    title: "📊 Server Information",
    description: "**%guild%** Statistics",
    color: "#5865F2",
    thumbnail: {
        url: "%guild_icon%"
    },
    fields: [
        {
            name: "👥 Members",
            value: "Total: **%members%**\nOnline: **%online%**\nBots: **%bots%**",
            inline: true
        },
        {
            name: "📝 Channels",
            value: "Text: **%text_channels%**\nVoice: **%voice_channels%**\nCategories: **%categories%**",
            inline: true
        },
        {
            name: "🎭 Roles",
            value: "Total: **%roles%**",
            inline: true
        },
        {
            name: "👑 Owner",
            value: "%owner%",
            inline: true
        },
        {
            name: "📅 Created",
            value: "%created%",
            inline: true
        },
        {
            name: "🚀 Boosts",
            value: "Level **%boosts%**",
            inline: true
        }
    ],
    footer: {
        text: "Server ID: %guild_id%",
        iconURL: "%guild_icon%"
    },
    defaultTimestamp: true,
}
```

This creates a rich, informative embed with organized fields, custom colors, and relevant server information.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.iynxdev.com/configuration-files/lang.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.