Roj guide

Everything Roj does, with screenshots. Roj (ڕۆژ) means both sun and day in Kurdish; read why.

Getting started

1. Install Roj from extensions.gnome.org, the Ubuntu PPA, the .deb packages or the tarball. See Install.
2. On Wayland, log out and back in once, so GNOME Shell loads it.
3. The Kurdish date appears next to the clock. Click it to open the calendar.
4. Choose your language: click Settings in the popup, then General, Languages.

How to

Short recipes for the things people ask most. Every screenshot is from a real GNOME Shell session.

Show the dates in your language

1. Click the date in the top bar, then Settings.
2. On General, under Languages, pick the Main date language: Sorani, Kurmanji, English, Persian or Arabic.
3. Pick Other calendars: the same language, the interface language, or each calendar in its own language.
4. Leave Interface language on automatic to follow the date, or pick one.

Show the Persian and Islamic days on every card

1. Open Settings, Appearance.
2. Under Day cards, switch on Persian (Jalali) day and Islamic (Hijri) day. Gregorian is on already.
3. Choose the layout: in a row under the day, or in the corners.

Add your country's public holidays

1. Open Settings, Events.
2. Next to Add a calendar, choose Online, then a country: Iraq, Iran, Turkey, Syria or Germany. Any .ics link works too, and File adds a local .ics or JSON file.
3. Give it a colour. Its days get a dot in the popup, and holidays turn red.

Change what the top bar shows

1. Open Settings, Formats.
2. Edit Top bar, or pick a preset with the list button. The preview under it updates as you type; see Patterns and tokens.
3. Under Appearance, Top bar, choose where it sits and how today's events are marked.

Convert a date

1. Click Convert in the popup, or open Settings, Converter.
2. Choose the calendar your date is in, then type it as YYYY-MM-DD or set the year, month and day.
3. Read it in every calendar. The copy button next to each line copies it.

Get the Kurdish days on your phone

Subscribe to the Kurdish events in Google Calendar or on an iPhone: see Kurdish events in Google Calendar, iPhone and Mac, or use the buttons on the live calendar.

The popup

From top to bottom:

• Header: the selected day in Kurdish, large, and under it the same day in the Gregorian, Persian and Islamic calendars, each with a coloured label.
• Month bar: the Kurdish month and year, and the Gregorian (and, if shown, Persian and Islamic) months it spans. The inner arrows change the month, the outer arrows the year. Click the month name to return to today. You can also scroll over the days.
• Weekdays: the week starts on Saturday by default, and the weekend is red.
• Day cards: see Day cards. Today is yellow, the selected day has a yellow outline, and a dot means the day has events.
• Legend: which colour belongs to which calendar.
• Events: the selected day's events. Holidays carry a red badge.
• Buttons: Today, Convert (opens the converter), Copy (copies the selected day with the Copy pattern) and Settings.
• Credits line: links to the author, the source, these docs and the website. You can hide it.

In Sorani, Persian and Arabic the popup is laid out right to left. Its size never changes when you pick another day.

The top bar

The top bar shows the Kurdish date with your pattern. When today has events, it also shows a marker; choose it under Appearance, Top bar, Today's events:

Day cards

The large number in each card is always the Kurdish day. Up to three small numbers, all the same size, can sit beside it:

Turn each on or off under Appearance, Day cards: any one, two or all three, in a row under the day or in the corners. Each small number uses the digits of its calendar's own language: Gregorian 012, Persian ۰۱۲, Islamic ٠١٢.

Languages and digits

Roj speaks Sorani, Kurmanji, English, Persian and Arabic. Under General, Languages you choose three things:

• Main date language: the language of the Kurdish date.
• Other calendars: the same language as the main date, the interface language, or each in its own language: Gregorian in English, Persian in Persian, Islamic in Arabic.
• Interface language: menus, labels and the settings window. By default it follows the main date language.

Friday 26 June 2026 in each language:

With each in its own language, a Sorani user sees ٥ی پووشپەڕی ٢٧٢٦ together with 26 June 2026, ۵ تیر ۱۴۰۵ and ١٠ محرم ١٤٤٨.

Digits

Numbers follow the calendar's own language, whatever language its words are in: the Gregorian date in English digits (2026), the Persian date in Persian digits (۱۴۰۵), the Islamic date in Arabic digits (١٤٤٨), and the Kurdish date in the digits of the main language: ٢٧٢٦ in Sorani, 2726 in Kurmanji. So a Sorani date line reads ٥ی پووشپەڕی ٢٧٢٦, 26 June 2026, ۵ تیر ۱۴۰۵, ١٠ محرم ١٤٤٨.

Each language's digits can be changed under General, Digits, and the change applies to its calendar: set Persian to Western digits and the Persian date becomes 1405. With Leading zero on automatic, only Western digits get a zero (05); ۵ and ٥ never do.

Sorani ezafe

Sorani writes a linking ی after the day when a month name follows (٥ی پووشپەڕ) and after the month when a year follows (پووشپەڕی ٢٧٢٦). Under General, Sorani ezafe you switch it on or off for each calendar. By default it is on for the Kurdish date only. It applies only to dates written in Sorani.

How dates are converted

The Kurdish calendar follows the sun. Each year begins at Newroz, the March equinox, usually on 21 March. Its months have the same lengths as the Persian (Jalali) calendar:

• months 1 to 6 have 31 days,
• months 7 to 11 have 30 days,
• month 12 has 29 days, or 30 in a leap year.

Only the year differs. Roj counts from the Median kingdom (700 BC): Kurdish year = Persian year + 1321. Some writers count from the fall of Nineveh (612 BC), which is Persian year + 1233; choose it under General, Year numbering.

One number for every calendar

Roj turns any date into a Julian Day Number (JDN), a plain count of days used by astronomers, and turns that number into the other calendars. For 26 June 2026:

Going the other way works the same. The mathematics comes from tsroj, the same engine as pyroj for Python, so Roj, tsroj and pyroj always agree. The Guide page in the settings shows these steps for today.

Settings, page by page

Open them with Settings in the popup, from the Extensions app, or with gnome-extensions prefs roj@0xdolan.github.io. The window follows your interface language, right to left for Sorani, Persian and Arabic.

General

• Languages: main date, other calendars, interface; year numbering.
• Digits: per language, with leading zero control.
• Sorani ezafe: per calendar, after the day and after the month.
• Names: traditional month name variants (Newroz or Xakelêwe, Gulan or Banemêr) and weekday name variants.
• Week: first day and weekend days.
• Islamic calendar: day adjustment.
• Backup and restore: see Backup.

Appearance

• Theme: follow the system, light or dark; popup text size; credits line.
• Top bar: position and order; show the date and/or the icon; today's events marker.
• Day cards: the small numbers and their placement, with a live preview of this week.
• Popup header: which calendars appear under the Kurdish date.
• Fonts: see Fonts.

Formats

One pattern each for the top bar, the four header lines and the Copy button. Each has a live preview, a list button to insert any token or apply a preset, and a button to restore the default. Below them, every token is shown for today in all four calendars.

Events

Show or hide events, mark days with dots, colour holidays, and set how often online calendars refresh. Manage the sources: the included Kurdish events, your files and online calendars. Each source has a colour and an on/off switch; files and links can also be treated as holidays. See Events and .ics.

Converter, Guide and About

Patterns and tokens

Patterns use the strftime tokens of tsroj and pyroj; everything else is kept as written. Examples for Friday 26 June 2026 at 21:05:

All tokens

• Persian month names always come from the Persian calendar and Islamic month names from the Arabic one, as in tsroj.
• The top bar updates every minute, or every second when its pattern has %S.
• Patterns cannot contain { or }; the preview tells you when a pattern is invalid.

Fonts

Roj splits text by script. Letters in the Arabic Unicode blocks (U+0600 to U+06FF, U+0750 to U+077F, U+08A0 to U+08FF, U+FB50 to U+FDFF, U+FE70 to U+FEFF), used by Sorani, Persian and Arabic, take the right-to-left font. Everything else, such as Kurmanji and English, takes the left-to-right font.

The included fonts load straight from the extension without being installed. On systems with Pango older than 1.56 (such as Ubuntu 24.04), the Fonts section offers to copy them to ~/.local/share/fonts/roj instead.

Events and .ics calendars

Roj shows events from three kinds of source, all managed on the Events page:

• Kurdish events, included: 43 days such as Newroz, Kurdish Language Day, Halabja and the Anfal, the 1991 uprising and Kurdistan Flag Day, also available for Google Calendar and iPhone.
• Files: your own JSON events, or any .ics file.
• Online calendars: any https:// or webcal:// .ics link. Online… offers public holidays for Iraq, Iran, Turkey, Syria and Germany, and Muslim holidays. They are cached in ~/.cache/roj and refreshed every 12 hours (you can change it), so they work offline.

JSON event format

{
  "name": { "ckb": "بۆنەکانی من", "kmr": "Bûyerên min", "en": "My events" },
  "events": [
    { "calendar": "kurdish", "month": 1, "day": 1, "holiday": true,
      "title": { "ckb": "نەورۆز", "kmr": "Newroz", "en": "Newroz", "fa": "نوروز", "ar": "نوروز" } },
    { "calendar": "gregorian", "month": 5, "day": 15,
      "title": { "ckb": "ڕۆژی زمانی کوردی", "kmr": "Roja Zimanê Kurdî" } },
    { "calendar": "islamic", "month": 10, "day": 1, "holiday": true,
      "title": "Eid al-Fitr" },
    { "calendar": "gregorian", "year": 2026, "month": 12, "day": 31,
      "time": "20:00", "title": "A one-off event" }
  ]
}

A bare list of events, without name, also works. Events with mistakes are skipped. Save… on the Events page writes a starter file, and roj events --month --file my-events.json checks one in a terminal.

What Roj reads from .ics files

• All-day and timed events: DTSTART, DTEND, SUMMARY, DESCRIPTION, CATEGORIES.
• Events over several days (up to 62) and yearly repeats (RRULE:FREQ=YEARLY).
• Holidays: events with a category containing “holiday”, or the description “Public holiday” (as in Google's national calendars). You can also treat every event of a source as a holiday.
• Cancelled events are skipped; other repeat rules show only the first occurrence.

Kurdish events in Google Calendar, iPhone and Mac

The included Kurdish events are also published as calendars. Subscribe to a link and the calendar stays up to date; download a file to import it once. The calendar page has one-click buttons and every event with its history.

• Google Calendar: on a computer, open Settings, Add calendar, From URL, paste a link and choose Add calendar. It then shows on your phone too. To import a file once, use Settings, Import and export.
• iPhone and iPad: Settings, Apps, Calendar, Calendar Accounts, Add Account, Other, Add Subscribed Calendar, paste a link, tap Next, then Save. Or tap Sorani, Kurmanji or English on the phone.
• Mac: in Calendar, File, New Calendar Subscription, then paste a link.
• Outlook: Add calendar, Subscribe from web, then paste a link.

Gregorian events repeat every year. Newroz and the two Eids follow other calendars, so they are listed for each year from 2020 to 2060. Eid dates use the arithmetic Hijri calendar and can differ by a day or two from the sighting of the moon. The files are also attached to every release, and roj ics writes the same file, plus your own events, with your Islamic day adjustment.

Converter

Open it with Convert in the popup.

1. Choose the calendar your date is in.
2. Set the year, month and day, or type YYYY-MM-DD and press Enter. The day range follows the month's real length.
3. Read the date in all four calendars, formatted with your header patterns, each with a copy button.

Details show the weekday, the distance from today, the Kurdish month in both dialects with its length, and the Julian Day Number.

Command line

roj gives the same answers in a terminal with the same engine, and, when run with gjs, your extension settings. make install, the .deb packages, the PPA and the tarball all install it, and with those the settings window can add it too, under About, Command-line tool. The extensions.gnome.org download leaves it out, as that site asks: install the roj package from the PPA or the .deb on the latest release, or run node extension/cli/roj.js from a checkout. It also runs with Node.js, so it works without GNOME, for example on Kali with Xfce. man roj has the full reference.

roj                                    # today in all four calendars
roj cal                                # this Kurdish month
roj cal 2727-01 --with g,p,i           # a month, with small numbers
roj convert 2026-06-26                 # Gregorian to every calendar
roj convert 2726-01-01 --from kurdish --to gregorian
roj format "%A %d %B %Y" --locale kmr
roj format "%d %B %Y" --date 1448-09-01 --from islamic
roj -l fa --secondary native           # Persian, each calendar in its own language
roj events --month                     # this month's events
roj events 2026-03-21 --file holidays.ics
roj ics --locale kmr > events.ics       # your events for Google or Apple Calendar
roj months                             # the twelve months of this year
roj tokens                             # every pattern token
roj convert 2026-10-25 --json          # machine-readable output

Exit status: 0 on success, 1 for an error such as an invalid date, 2 for a usage error.

Backup and restore

General, Backup and restore, Export… saves every setting (languages, patterns, fonts, event sources and the rest) to a roj-settings-DATE.json file. On a new computer or a fresh install, Import… that file. Settings that do not apply, for example from a newer version, are skipped and counted. Reset… returns everything to the defaults.

Font files and event files are saved by path. Copy them to the same place on the new computer, or load them again.

Troubleshooting

I installed Roj but nothing appears

On Wayland, GNOME Shell loads new extensions only after you log out and back in. Then switch Roj on in the Extensions app, or run gnome-extensions enable roj@0xdolan.github.io. Roj needs GNOME Shell 45 or newer (gnome-shell --version).

The roj command is not found

make install puts it in ~/.local/bin. If that folder is not on your PATH, open a new terminal, or add export PATH="$HOME/.local/bin:$PATH" to your shell's startup file.

The text is not in Vazirmatn or Manrope

On Pango older than 1.56, use Appearance, Fonts, Install the included fonts, then log out and back in.

The Islamic date is a day off

Set General, Islamic calendar, Day adjustment to match the moon sighting where you live.

An online calendar shows an error

Roj keeps the last good copy and tries again at the next refresh. Use the refresh button on the Events page to retry now, and check that the link opens in a browser.

Report a problem

Open an issue on GitHub with your GNOME Shell version and, if it helps, a settings export.