rnmhdn/README.md

Cultural Date Widget for Awesome WM

A bilingual date widget for Awesome Window Manager that displays the current date in both Persian (Solar Hijri) and French (Gregorian) formats, updating every minute.

Preview

The widget displays dates in this format:

📅 ۲۱ اردیبهشت | mardi 21 mai

Prerequisites

This widget requires both Persian (fa_IR.UTF-8) and French (fr_FR.UTF-8) locales to be installed on your system.

Installing Locales

Ubuntu/Debian

# Install and generate locales
sudo locale-gen fa_IR.UTF-8
sudo locale-gen fr_FR.UTF-8

# Verify installation
locale -a | grep -E "fa_IR|fr_FR"

Note: If locale-gen is not found, install the locales package first:

sudo apt install locales

Arch Linux

# Edit locale configuration
sudo vim /etc/locale.gen

# Uncomment these lines (remove the # at the start):
# fa_IR.UTF-8 UTF-8
# fr_FR.UTF-8 UTF-8

# Generate locales
sudo locale-gen

# Verify installation
locale -a | grep -E "fa_IR|fr_FR"

Fedora/RHEL

# Install locale source files if needed
sudo dnf install glibc-locale-source

# Generate locales
sudo localedef -i fa_IR -f UTF-8 fa_IR.UTF-8
sudo localedef -i fr_FR -f UTF-8 fr_FR.UTF-8

# Verify installation
locale -a | grep -E "fa_IR|fr_FR"

openSUSE

# Edit locale configuration
sudo vim /etc/locale.gen

# Uncomment these lines:
# fa_IR.UTF-8
# fr_FR.UTF-8

# Generate locales
sudo locale-gen

# Verify installation
locale -a | grep -E "fa_IR|fr_FR"

Void Linux

# Edit locale configuration
sudo vim /etc/default/libc-locales

# Uncomment or add:
# fa_IR.UTF-8 UTF-8
# fr_FR.UTF-8 UTF-8

# Reconfigure glibc-locales
sudo xbps-reconfigure -f glibc-locales

# Verify installation
locale -a | grep -E "fa_IR|fr_FR"

Installation

Create the widgets directory if it doesn't exist:

mkdir -p ~/.config/awesome/widgets

Create the widget file:

vim ~/.config/awesome/widgets/cultural_date.lua

Add the following code:

local wibox = require("wibox")
local awful = require("awful")
local gears = require("gears")

local M = {}

M.widget = wibox.widget.textbox()
M.widget:set_align("center")

local function update_cultural_date()
    awful.spawn.easy_async_with_shell(
        'PERSIAN=$(LC_TIME=fa_IR.utf8 date "+%d %B"); ' ..
        'FRENCH=$(LC_TIME=fr_FR.UTF-8 date "+%A %d %B"); ' ..
        'echo "$PERSIAN | $FRENCH"',
        function(stdout)
            local date_str = stdout:gsub("\n", "")
            if date_str == "" or date_str:match("error") then
                M.widget:set_text("📅 ?")
            else
                M.widget:set_text(" 📅 " .. date_str)
            end
        end
    )
end

-- Update every minute
gears.timer({
    timeout = 60,
    call_now = true,
    autostart = true,
    callback = update_cultural_date
})

return M

Edit your rc.lua:

vim ~/.config/awesome/rc.lua

Add near the top (after your existing require lines):

local cultural_date = require("widgets.cultural_date")

Find your wibar setup (search for s.mywibox:setup) and add the widget. For example:

s.mywibox:setup {
    layout = wibox.layout.align.horizontal,
    { -- Left widgets
        -- ... your existing widgets ...
    },
    cultural_date.widget, -- Center widget
    { -- Right widgets
        -- ... your existing widgets ...
    }
}

Restart Awesome WM with Ctrl + Super + r.

Customization

You can modify the date formats by editing the date command strings in ~/.config/awesome/widgets/cultural_date.lua:

'PERSIAN=$(LC_TIME=fa_IR.utf8 date "+%d %B"); ' ..
'FRENCH=$(LC_TIME=fr_FR.UTF-8 date "+%A %d %B"); ' ..

Common format options:

%A - Full weekday name (e.g., lundi, دوشنبه)
%B - Full month name (e.g., mai, اردیبهشت)
%d - Day of month with leading zero (01-31)
%e - Day of month without leading zero (1-31)
%Y - Year (e.g., 2026)
%m - Month number (01-12)

For example, to add the year to the French date:

'FRENCH=$(LC_TIME=fr_FR.UTF-8 date "+%A %d %B %Y"); ' ..

Troubleshooting

Widget shows "📅 ?"

This means the locales aren't installed or the date commands failed. Test them manually:

LC_TIME=fa_IR.utf8 date "+%d %B"
LC_TIME=fr_FR.UTF-8 date "+%A %d %B"

Both commands should return properly formatted dates. If you see errors or English text, the locales are not correctly installed.

Check installed locales

locale -a | grep -E "fa_IR|fr_FR"

You should see both fa_IR.utf8 (or fa_IR.UTF-8) and fr_FR.UTF-8 in the output.

Awesome WM not picking up changes

Restart Awesome WM after installing locales or editing the widget:

Default shortcut: Ctrl + Super + r
Or run: echo 'awesome.restart()' | awesome-client

Persian text not displaying correctly

Ensure you have a font installed that supports Persian/Arabic characters:

# Ubuntu/Debian
sudo apt install fonts-noto

# Arch
sudo pacman -S noto-fonts

# Fedora
sudo dnf install google-noto-sans-arabic-fonts