Meet persianutils: Bits and Pieces for Your Farsi Application

Updated: 2026-10 Published: 2026-10

Back in 2013, I was looking for a calendar converter. Iranian/Jalali to Gregorian and back. Something I could use from Scala or Java.

Surprisingly, I couldn’t find a reliable open-source option for the JVM. The options I came across had troublesome edge cases or seemed reliable only within a fairly narrow window: roughly fifty years either side of the present.

I wanted something with stronger guarantees.

Luckily, Someone Had Done the Astronomy

Dr Kazimierz M. Borkowski had already done the astronomical calculations and documented an algorithm in his paper, The Persian Calendar for 3000 Years.

The algorithm was rather involved. But the calculations, the reasoning and the implementation were there to study.

And, that was enough for me.

I ported it to Scala, made it usable from Java, and released it as persianutils.

The astronomical work deserves the credit here. Having that documented foundation gave me something substantial to build on, with a scope reaching well beyond the dates immediately around us.

A Little Library Grows

Over the years, other enthusiasts joined in. Contributions helped improve the library and broaden what it could do. What began as a solution to my calendar problem became a shared collection of utilities for programmers serving Farsi-speaking users.

Then I noticed another familiar pattern in my own projects: I kept copying and pasting the same text-handling helpers.

Normalising characters and digits, tidying up spaces, and of course the half-spaces!

If you’ve worked with Farsi text, especially text produced on older Windoze machines, you’ll know that their keymaps weren’t the most accurate. They introduced tons of incorrect or non-standard characters into the text.

After carrying that code from project to project, putting it into persianutils felt like the natural next step.

The Useful Bits Between Your Application and Its Users

Today, persianutils brings together calendar conversion, numbers and dates written out in Farsi, and configurable Farsi text normalisation. It’s available to Scala and Java programmers, with builds for the JVM and Scala.js.

That’s how persianutils came about and grew.

Take a Look

If you’re building software for Farsi-speaking users, have a look at the documentation. It has examples in Scala and Java, installation instructions, and the details of what the library handles.

The source is on GitHub, under the Apache 2.0 licence. Issues, examples of troublesome inputs, and contributions are welcome.

I hope it saves you a little of the searching and copy-pasting.

Bahman's Musings