DEV Community

Mobin Valadi
Mobin Valadi

Posted on

Bridging Cultures with Code: A Developer's Guide to the Kurdish Calendar in Go with `kurdical`

#kurdish #kurdistan #go #kurd

In software development, code often serves as a universal language. Yet, at its most impactful, it can also become a powerful medium for cultural preservation and expression. The intersection of technology, history, and culture is where tools emerge that not only solve technical problems but also build bridges of understanding. The kurdical Go library is a prime example—a powerful and thoughtfully designed module that enables developers to work seamlessly with the Kurdish calendar system. With a stable v1.0.0 release and 100% test coverage, kurdical provides a reliable foundation for building culturally-aware applications.

This article serves as a comprehensive, hands-on tutorial for installing, using, and understanding the core features of the kurdical library. We will walk through everything from basic date conversions to leveraging its support for diverse dialects and historical epochs. By the end, you will have learned how to integrate a culturally significant calendar system into your Go applications, making your software more inclusive, accurate, and globally aware.

1. The Kurdish Calendar: A Glimpse into History

To fully appreciate the design and features of the kurdical library, it is essential to understand the cultural and historical context of the calendar it represents. The Kurdish calendar is an independent solar calendar system, with its origins and structure deeply rooted in significant events in Kurdish history.

The library provides support for two distinct historical epochs, each aligning the calendar's starting point with a pivotal moment. The choice of epoch is a critical configuration parameter that depends on the specific historical context your application needs to represent.

  • Median Kingdom (Diako) epoch: This epoch begins with the establishment of the Median kingdom by Diako.
  • Fall of Nineveh (Cyaxares) epoch: This epoch marks its beginning from the fall of Nineveh by Cyaxares.

The core calculation logic is straightforward: the Kurdish year is determined by adding an epoch-specific offset to the base solar calendar year. The calculation can be expressed as a simple formula:

  • Median Kingdom epoch:
  • Fall of Nineveh epoch:

The adjustments for each epoch are presented below.

Epoch Historical Adjustment
Median Kingdom Base year + 1321
Fall of Nineveh Base year + 1233

With this historical foundation in place, we can now proceed to the practical steps of integrating this powerful calendar system into a Go project.

2. Getting Started: Installation and Setup

Integrating kurdical into a Go project is a straightforward one-step process using the standard go get command. This command fetches the package directly from its source repository, downloads it, and makes it available for use in your code.

To install the library, simply run the following command in your terminal:

go get github.com/rojcode/kurdical
Enter fullscreen mode Exit fullscreen mode

With the library now installed in your Go workspace, you are ready to write your first piece of code and begin exploring its features.

3. Core Functionality: Mastering Date Conversions

This section forms the core of the tutorial, demonstrating the library's fundamental capability: two-way conversion between the standard Gregorian calendar and the Kurdish calendar. These examples showcase kurdical's primary function and highlight its precision and ease of use.

3.1 Basic Gregorian to Kurdish Conversion

The most common use case is converting a standard Gregorian date into its Kurdish equivalent. The library simplifies this with the GregorianToKurdish function. This function takes a standard Go time.Time object as its primary input, along with two configuration constants: one for the desired dialect (e.g., kurdical.Sorani) and one for the historical epoch (e.g., kurdical.MedianKingdom).

3.2 Round-Trip Conversion (Kurdish back to Gregorian)

A critical test for any conversion library is its ability to perform a "round-trip" conversion—transforming a value and then transforming it back to its original state. This process validates the library's correctness and builds confidence in its reliability for production use.

The following code demonstrates a complete round-trip. First, it converts the Gregorian date March 21, 2023, into the Kurdish calendar. Then, it immediately uses the resulting KurdishDate object to convert it back to Gregorian, confirming the accuracy of the process.

package main

import (
    "fmt"
    "time"

    "github.com/rojcode/kurdical"
)

func main() {
    // 1. Define the initial Gregorian date
    t := time.Date(2023, 3, 21, 0, 0, 0, 0, time.UTC)
    fmt.Printf("Original Gregorian date: %s\n", t.Format("2006-01-02"))

    // 2. Convert from Gregorian to Kurdish
    k := kurdical.GregorianToKurdish(t, kurdical.Sorani, kurdical.MedianKingdom)
    fmt.Printf("Kurdish date: %d-%d-%d %s\n", k.Year, k.Month, k.Day, k.MonthName)

    // 3. Convert back from Kurdish to Gregorian (Round-trip)
    g, err := kurdical.KurdishToGregorian(k)
    if err != nil {
        fmt.Println(err)
    } else {
        fmt.Printf("Round-trip Gregorian date: %s\n", g.Format("2006-01-02"))
    }
}
Enter fullscreen mode Exit fullscreen mode

Running this code produces the following output, showing a successful round-trip conversion:

Original Gregorian date: 2023-03-21
Kurdish date: 2723-1-1 خاکه‌لێوه
Round-trip Gregorian date: 2023-03-21

With the core conversion functionality established, we can now explore the library's more culturally nuanced features.

4. Embracing Diversity: Dialects and Epochs

The kurdical library's true power lies not just in date conversion, but in its deep respect for Kurdish cultural diversity. This is evident in two key features: comprehensive support for multiple Kurdish dialects and the ability to work with different historical epochs. A key technical assurance is that the library is built with UTF-8 encoding, ensuring that all Kurdish characters display correctly.

4.1 Working with 5 Kurdish Dialects

The library provides authentic month names for five major Kurdish dialects, ensuring that applications can communicate with users in the most appropriate and respectful way.

package main

import (
    "fmt"
    "time"

    "github.com/rojcode/kurdical"
)

func main() {
    t := time.Date(2023, 3, 21, 0, 0, 0, 0, time.UTC)

    dialects := map[string]kurdical.Dialect{
        "Sorani":   kurdical.Sorani,
        "Kurmanji": kurdical.Kurmanji,
        "Laki":     kurdical.Laki,
        "Hawrami":  kurdical.Hawrami,
        "Kalhuri":  kurdical.Kalhuri,
    }

    fmt.Println("Month names for 2023-03-21 in various dialects:")
    for name, dialect := range dialects {
        k := kurdical.GregorianToKurdish(t, dialect, kurdical.MedianKingdom)
        fmt.Printf("%-10s %s\n", name+":", k.MonthName)
    }
}
Enter fullscreen mode Exit fullscreen mode

The output clearly illustrates the authentic month names provided for each dialect:

Month names for 2023-03-21 in various dialects: > Sorani: خاکه‌لێوه
Kurmanji: نیسان
Laki: په‌نجه
Hawrami: نه‌ورۆز
Kalhuri: جه‌ژنان (جه‌شنان)

4.2 Comparing Historical Epochs

As discussed earlier, the library supports two historical starting points for the calendar. Developers can select between the MedianKingdom and FallOfNineveh epochs, which directly impacts the resulting date.

package main

import (
    "fmt"
    "time"

    "github.com/rojcode/kurdical"
)

func main() {
    t := time.Date(2023, 6, 15, 0, 0, 0, 0, time.UTC)

    // Median Kingdom epoch
    kMedian := kurdical.GregorianToKurdish(t, kurdical.Sorani, kurdical.MedianKingdom)
    fmt.Printf("Median Kingdom: %d-%d-%d\n", kMedian.Year, kMedian.Month, kMedian.Day)

    // Fall of Nineveh epoch
    kNineveh := kurdical.GregorianToKurdish(t, kurdical.Sorani, kurdical.FallOfNineveh)
    fmt.Printf("Fall of Nineveh: %d-%d-%d\n", kNineveh.Year, kNineveh.Month, kNineveh.Day)

    fmt.Printf("Year difference: %d\n", kMedian.Year-kNineveh.Year)
}
Enter fullscreen mode Exit fullscreen mode

The output highlights the different dates calculated for each epoch, with a consistent year difference of 88 years between them.

Median Kingdom: 2723-3-25
Fall of Nineveh: 2635-3-25
Year difference: 88

5. Advanced Usage: Formatting and Error Handling

For a library to be truly production-ready, it must offer both flexibility and robustness. kurdical delivers on both fronts by providing advanced formatting options, ergonomic helper functions, and built-in error handling.

5.1 Custom Formatting with Kurdish Digits

The library includes a powerful KFormat function for custom date string formatting. KFormat leverages the familiar layout strings from Go's standard library time.Format method. However, it enhances the output by localizing it with Kurdish month names and Eastern Arabic numerals (٠ ١ ٢ ٣ ٤ ٥ ٦ ٧ ٨ ٩).

package main

import (
    "fmt"
    "time"

    "github.com/rojcode/kurdical"
)

func main() {
    t := time.Date(2023, 3, 21, 0, 0, 0, 0, time.UTC)
    k := kurdical.GregorianToKurdish(t, kurdical.Sorani, kurdical.MedianKingdom)

    formatted, err := k.KFormat("2006-01-02 January")
    if err != nil {
        fmt.Println("Error:", err)
    } else {
        fmt.Printf("Formatted: %s\n", formatted)
    }
}
Enter fullscreen mode Exit fullscreen mode

Output: > Formatted: ٢٧٢٣-٠١-٠١ خاکه‌لێوه

5.2 Robust Date Validation

The kurdical library is designed to gracefully manage invalid dates, returning clear and descriptive errors.

Example: Invalid Month

invalidKurdish := kurdical.KurdishDate{
    Year:  2725,
    Month: 13, // Invalid month
    Day:   24,
    Epoch: kurdical.MedianKingdom,
}
_, err := kurdical.KurdishToGregorian(invalidKurdish)
// Error: invalid month: 13
Enter fullscreen mode Exit fullscreen mode

Example: Invalid Day

invalidDay := kurdical.KurdishDate{
    Year:  2725,
    Month: 1,
    Day:   32, // Invalid day
    Epoch: kurdical.MedianKingdom,
}
_, err := kurdical.KurdishToGregorian(invalidDay)
// Error: invalid day: 32 for month 1 in year 2725
Enter fullscreen mode Exit fullscreen mode

5.3 Handling Weekdays and Date-Only Conversions

The kurdical.WeekdayNames slice provides Kurdish names for the days of the week. For convenience, the library also offers date-only functions like GregorianToKurdishDate, which accept integer inputs for year, month, and day.

// Example 1: Get the Kurdish weekday name
t := time.Date(2023, 3, 21, 0, 0, 0, 0, time.UTC)
kWithTime := kurdical.GregorianToKurdish(t, kurdical.Sorani, kurdical.MedianKingdom)
fmt.Printf("Weekday: %s\n", kurdical.WeekdayNames[kWithTime.Weekday])

// Example 2: Use the date-only conversion function
kDateOnly := kurdical.GregorianToKurdishDate(2023, 3, 21, kurdical.Sorani, kurdical.MedianKingdom)
fmt.Printf("Date-only conversion: %d-%d-%d\n", kDateOnly.Year, kDateOnly.Month, kDateOnly.Day)
Enter fullscreen mode Exit fullscreen mode

6. Conclusion: Adding a Powerful Tool to Your Go Toolkit

Throughout this guide, we have explored the key capabilities of the kurdical Go library. From accurate, two-way conversions to deep cultural nuances like dialect and epoch support, the library proves itself to be a comprehensive solution.

Beyond technical utility, kurdical stands as an important contribution to cultural representation in technology. By making a rich calendar system accessible, it helps ensure that diverse histories and languages find their place in the digital world. We encourage developers to explore the kurdical library for projects requiring sophisticated localization or a connection to the region.

Top comments (0)