arabic-datetime

Author: Khaldevmedia

Description: A Node package that helps you output dates in Arabic as strings, with formatting specific to each Arab country.

Version: 1.0.0

Note: This Node package was created after the success of our arabic-datetime Python package.

Using The Package for Date Formatting

This Node package is designed to simplify Arabic date formatting in your project by providing easy-to-use date formatting functions. It can be used to simplify your frontend or backend operations. Instead of installing a full internationalisation package, you can use this package to display Arabic dates formatted according to local settings, whether the response content type is HTML or JSON. It's lightweight, efficient and easy to integrate into your existing project. By using this package, you can keep your backend lean and focused, while still providing a localised user experience.

Month names in Arabic

There are 5 groups of month names in Arabic.

Syriac names:

The Syriac names of months are used in Syria, Palestine Lebanon, Iraq and Jordan:

Roman names (group 1):

The Roman names (group 1) of months are used in Egypt, Yemen, Sudan, Libya, Djibouti, Comoro, Somalia, Saudi Arabia, United Arab Emirates, Qatar, Oman, Bahrain and Kuwait:

Roman names (group 2):

The Roman names (group 2) of months are used in Morocco:

Roman names (group 3):

The Roman names (group 3) of months are used in Mauritania:

French names:

The French names of months are used in Algeria and Tunisia:

Arabic Numerals

There are two groups of Arabic numerals used in the Arab countries.

Eastern Arabic Numerals

They are used in all Arab countries except Algeria, Tunisia, Morocco and Mauritania:

٠ ١ ٢ ٣ ٤ ٥ ٦ ٧ ٨ ٩

Western Arabic Numerals

They are mainly used in Algeria, Tunisia, Morocco and Mauritania. However, they are also used in the other Arab countries that use the eastern Arabic numerals:

0 1 2 3 4 5 6 7 8 9

Numerals Options

You can use the eastern or the western Arabic numerals regardless of the month names group you use. As demonstrated below, there is always a default numerals' type depending on the method used.

Installation

npm install arabic-datetime

Examples

1. Date

The ArabicDate class has several methods that return an Arabic date as a string.

A specific method for every month names group

import { ArabicDate } from 'arabic-datetime';

// Create arabicDate object from a JavaScript Date instance
const jsDate: Date = new Date(1980, 7, 16); // Months are 0-based, so 7 represents August
const arabicDate: ArabicDate = new ArabicDate(jsDate);

// Use each method to create the Arabic date strings
const syriacDateFormat: string = arabicDate.syriacNames();
const egyptDateFormat: string = arabicDate.roman1Names();
const moroccoDateFormat: string = arabicDate.roman2Names();
const algeriaDateFormat: string = arabicDate.frenchNames();

console.log(syriacDateFormat); // output 16 آب 1980
console.log(egyptDateFormat); // output 16 أغسطس 1980
console.log(moroccoDateFormat); // output 16 غشت 1980
console.log(algeriaDateFormat); // output 16 أوت 1980

// To use Eastern Arabic Numerals pass true to the method you use
const syriacDateFormatEastern: string = arabicDate.syriacNames(true);
console.log(syriacDateFormatEastern); // output ١٦ آب ١٩٨٠

Note:

When you combine Western Arabic numerals or western punctuations with Arabic characters they appear messed up if the text direction in the target is set to left to right or dir=ltr in HTML.

In order for the Arabic date to appear properly, especially if it uses western Arabic numerals, the direction of the text in the interface you are using must be right to left. If you insert the date into an HTML element set text direction to rtl. If the text direction in the whole HTML document is set to rtl you should be OK.

<p dir="rtl">16 آب 1980</p>
<p dir="rtl">16 أوت 1980</p>

The result will look like this:

A dual date name method

It's very common that two month names are used at the same time to display the date in Arabic with the second one put between parentheses, like this:

To get the Arabic date formatted like this, use the dualNames method:

import { ArabicDate } from 'arabic-datetime';

// Create arabicDate object from a JavaScript Date instance
const jsDate: Date = new Date(1980, 7, 16);
const arabicDate: ArabicDate = new ArabicDate(jsDate);

// Use the dualNames() method to return an Arabic date string that shows two names of the month.
// This method takes 3 arguments: 2 strings for the month group names (the second one
// will be put between parentheses), and a boolean to determine whether to format the
// Arabic date with the Eastern Numerals or not:
const dualDateRoSy: string = arabicDate.dualNames('syriac', 'roman1', false);
console.log(dualDateRoSy); // output 16 أغسطس (آب) 1980

// If you don't pass the third argument, the default is false. Also you can use
// named arguments if you're in TypeScript by passing an options object to clarify intent.

// To use Eastern Arabic Numerals, pass true as the third argument.
// We will also switch the month names in this example:
const dualDateSyRo: string = arabicDate.dualNames('syriac', 'roman1', true);
console.log(dualDateSyRo); // output ١٦ آب (أغسطس) ١٩٨٠

Accepted values for group names (Look above to see which Arab country uses which names):

"syriac" : For Syriac names
"roman1" : For Roman names (group 1)
"roman2" : For Roman names (group 2)
"french" : For French names

A method that takes a country code to return the corresponding date format

import { ArabicDate } from 'arabic-datetime';

// Create arabicDate object from a JavaScript Date instance
const jsDate: Date = new Date(1980, 7, 16);
const arabicDate: ArabicDate = new ArabicDate(jsDate);

// Use of byCountryCode() method. It takes countryCode as a string
// If you don't pass true or false besides the country code string
// the method will return the numeral type that is most common in that country
const syriacDateFormat: string = arabicDate.byCountryCode('SY');
const algeriaDateFormat: string = arabicDate.byCountryCode('DZ');
console.log(syriacDateFormat); // output ١٦ آب ١٩٨٠
console.log(algeriaDateFormat); // output 16 أوت 1980

// But if you want to force the numeral type, pass as a second argument
// true for eastern numerals and false for western numerals
const syriacDateFormatWestern: string = arabicDate.byCountryCode('SY', false);
const algeriaDateFormatEastern: string = arabicDate.byCountryCode('DZ', true);
console.log(syriacDateFormatWestern); // output 16 آب 1980
console.log(algeriaDateFormatEastern); // output ١٦ أوت ١٩٨٠

List of country codes:

DZ: Algeria
BH: Bahrain
KM: Comoros
DJ: Djibouti
EG: Egypt
IQ: Iraq
JO: Jordan
KW: Kuwait
LB: Lebanon
LY: Libya
MR: Mauritania
MA: Morocco
OM: Oman
PS: Palestine
QA: Qatar
SA: Saudi Arabia
SO: Somalia
SD: Sudan
SY: Syria
TN: Tunisia
AE: United Arab Emirates
YE: Yemen

2. Time

The ArabicTime class has one method that returns Arabic time as a string using the Eastern Arabic numerals. It takes two parameters: format with default value as "HMS" and separator with default value as ":".

import { ArabicTime } from 'arabic-datetime';

const jsDate: Date = new Date(1980, 7, 16, 12, 30, 45, 123);
const arabicTime: ArabicTime = new ArabicTime(jsDate);
const hmsTime: string = arabicTime.time('HMS');
const hmTime: string = arabicTime.time('HM');
const hmSlashTime: string = arabicTime.time('HM', '/');
console.log(hmsTime); // output ١٢:٣٠:٤٥
console.log(hmTime); // output ١٢:٣٠
console.log(hmSlashTime); // output ١٢/٣٠

Valid format values:

"H": Shows hour only.
"HM": Shows hour and minute.
"HMS": Shows hour, minute and second.
"HMSF": Shows hour, minute, second and millisecond.

Note:

As explained above, make sure that the direction of the text in which the Arabic time is inserted is right to left.

<p dir="rtl">١٢:٣٠:٤٥</p>
<p dir="rtl">الساعة حالياً: ١٢:٣٠:٤٥</p>

The result will look like this:

License

GNU General Public License v3.0.

Contact

www.khaldevmedia.com