Non-Gregorian calendars inside moment.js #1454

ebraminio opened this Issue Feb 1, 2014 · 10 comments


None yet

8 participants

ebraminio commented Feb 1, 2014 edited

MediaWiki's date formatter can easily generates non-Gregorian calendars output.

This is a copy of the related parts of the documentation:

Non-Gregorian calendars
xmj Day of the month
xmF Full month name
xmn Month index
xmY Full year
Iranian (Jalaly)
xij Day of the month
xiF Full month name
xin Month index
xiY Full year
xiy 2-digit year
xjj Day of the month
xjF Full month name
xjt Number of days in month
xjx Genitive form of the month name
xjn Month number
xjY Full year
Thai solar
xkY Full year
Minguo/Juche year
xoY Full year
Japanese nengo
xtY Full year

With considering this and an example calendar algorithm from MediaWiki, this is my proposal:

  • Define a separate folder/script inside moment.js project for actual calendar algorithm implementation (xij, xiF, . . .) but don't include that on moment.js core
  • Original modules of extension calendars should just include the English translation and locales modules which handle the translation of needed calendars for a locale. A fallback to English (which provided by the algorithm itself) should be done also when translation is not available on a specific locale module
  • Locale module should define their default date format with their related calendars
  • Similar to MediaWiki date format convention, what available on above table (or same moment-jalaali?)

With this design, using Iranian calendar on English and Gregorian calendar on Persian for example [both use-cases are important] would be easy.

I think if we decide about a design, implementing the needed change will be easier.

globalize also has support of Persian calendar for example.

Thank you and sorry about spell/grammar/facts errors available

ichernev commented Feb 1, 2014

OK, so you're suggesting

  • add support for plug-in-able calendar systems
  • add support for plug-in-able format tokens

I have a few questions:

  • don't we also need plug-in-able parsing tokens
  • do you expect to add special functions for those calendars (like getJapaneseYear) or we can just use an extensible get/set interface. The names can be the x-names from above, although I think there should be a longer, more readable version
  • what about local, utc and zoned version of those. Is there anything special to know?

extensible get/set

moment.registerUnit(name, getter, setter)
  • name is year (built-in), xmj (plug-in), etc
  • getter = function(moment, name) {} returning the value of the unit for a given moment object. name is given to allow reuse
  • setter = function(moment, value, name) {} setting the value of the unit for the given moment object. name is given to allow reuse

extensible parsing tokens

moment.registerParseToken(token_regex, string_regex[, loose_string_regex], handler)
  • token_regex is like xmj
  • string_regex is a regex used to match in strict parsing, for example\d{3}
  • loose_string_regex is a regex to use in non-strict parsing. Defaults to string_regex
  • handler = function(token, parsedInput, config) record a parsed token into config, for example (for all /xm./ tokens)
handler = function(token, parsedInput, config) {
  config._xm[token.charAt(2)] = parseInt(parsedInput, 10)

extensible converters (calendars)

moment.registerConverter(converter, inputFmt, outputFmt)
  • converter = function(config) {} converters the data stored in config from the handler to something understandable. Right now moment supports isoweek/isoWeekDay/isoWeekYear, week/weekDay/weekYear, year/dayOfYear, and day/month/year.
  • inputFmt -- the name of the format from which this is converting
  • outputFmt -- the name of the format to which this is converting

For example {inputFmt: 'xm', outputFmt: 'dayOfYear'} (but I really don't like the name xm).

input/output formats would be used to define in which orders should the converters run, and would enable sharing of code in the converter. We might need to also record which converters need to run based on the format tokens used, so that we don't run 100 unused converters. We can also get rid of them and depend on the registration order (run last registered first).

extensible formatting tokens

moment.registerFormatToken(token, formatter)
  • token is like MM
  • formatter = function(moment, token) {} returns the string to be displayed

@icambron any thoughts? I think this is a good candidate for the 3.0 release. It would need moderate refactoring throughout the code, but it shouldn't be too hard.

ebraminio commented Feb 1, 2014 edited


  • Yes, I guess
  • I don't think
  • No. I don't remember anything like this on MediaWiki at least

I like a transparent solution where a small project won't need to care about local calendars but would automatically get a good localized UI but also a more advance project can have options for doing different things. On libicu every locale has a default calendar, Persian (Iranian) calendar for fa and this. Instead complete transparency, another solution could be providing some tokens for locale preferred calendars (alias to their real token but independent from exact calendar).

ghost commented Sep 8, 2014



@ichernev How far along is this feature? This seems like it could be tied into extensibility with #1241

glittle commented Jun 20, 2016

What is the status of pluggable calendar systems? Is it possible today? Is there documentation somewhere? Or does it still require plugins to implement?

mj1856 commented Jun 21, 2016 edited

Still requires plugins. A few are mentioned in the docs.

mhf-ir commented Jul 5, 2016

For better algorithm of special calendars reference is here: with C,C++ and Java codes :

  • Japanese
  • Buddhist
  • Chinese
  • Persian
  • Indian
  • Islamic
  • Hebrew
  • Indian
  • Coptic
  • Ethiopic

This will help for better i18n and l10n apps


How common are the other calendars? I know they are useful for traditional festivities and religious events, but to what extent are they really used in these countries in day-to-day activities? (like scheduling an appointment with a dentist) I'm just curious!

glittle commented Jul 28, 2016

I don't know about others, but my interest is in the Wondrous calendar (Badí'). So far, it is a religious calendar used by the Baha'i Faith to schedule religious events, etc. However, at its core, it is a very practical solar calendar that will likely become better known in the years to come.

@NumBerNanA NumBerNanA referenced this issue in T00rk/bootstrap-material-datetimepicker Oct 3, 2016

how to change year display but how old value for calculate? #117

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment