PersianTools is a standalone, library-agnostic JavaScript that enables some of the Persian features for use in the JavaScript.
- Convert Persian words to the number.
- Convert Numbers to Persian words.
- Add and remove commas to numbers.
- Convert Persian numbers to Arabic or English numbers and vice versa.
- Validate Iranian national number(code-e Melli).
- Validate Iranian legal id(shenase hoghoghi).
- Find city and province name by national code(code-e Melli).
- Bill calculator.
- Check Iranian Sheba(IBAN) validation and recognize bank information by sheba code.
- Validate Bank card number.
- Find Bank's name by Card number.
- Validate the correctness of the text of the Persian language and clear the Arabic letters in the Persian text.
- Fix Persian characters in URL.
- Fix Persian zero-width non-joiner(Replace spaces by half-space)
- Convert Jalaali date-time into a time ago
- Get the Remaining Time of the Date
- Validate and find information of phone number.
- Find capital city by province name
There are two main ways to get PersianTools.js in your JavaScript project: via script tags or by installing it from NPM and using a build tool like Parcel, WebPack, or Rollup.
Add the following code to an HTML file:
<html>
<head>
<!-- Load PersianTools.js -->
<script src="https://cdn.jsdelivr.net/npm/@persian-tools/persian-tools/build/persian-tools.umd.js"></script>
<!-- Place your code in the script tag below. You can also use an external .js file -->
<script type="text/javascript">
// Notice there is no 'import' statement. 'all persian-tools functions like digitsEnToFa, etc...' is available on the index-page
// because of the script tag above.
// Takes a string made of English digits only, and returns a string that represents the same number but with Persian digits
var convertToFa = PersianTools.digitsEnToFa(1234567);
// etc...
</script>
</head>
<body></body>
</html>Open up that html file in your browser, and the code should run!
Install the PersianTools to your project using yarn or npm. Note: Because
we use ES2017 syntax (such as import), this workflow assumes you are using a modern browser, or a bundler/transpiler
to convert your code to something older browsers understand.
$ npm install --save @persian-tools/persian-toolsor
$ yarn add @persian-tools/persian-toolsimport * as persianTools from "@persian-tools/persian-tools";
// or
import { digitsEnToFa } from "@persian-tools/persian-tools";
// Takes a string made of English digits only, and returns a string that represents the same number but with Persian digits
const convertedToFa = persianTools.digitsEnToFa(1234567);
// or
const convertedToFa = digitsEnToFa(1234567);Let's take a look at what an example test case would look like using Persian-tools.
| Options | Description | Default |
|---|---|---|
fuzzy(Beta) |
Fix typo in the Persian words by using levenshtein algorithm |
false |
digits |
Result will be converted to the English or Persian digits | en |
addCommas |
Commas will be added to the Result | false |
- Convert with no option
import { wordsToNumber } from "@persian-tools/persian-tools";
wordsToNumber("منفی سه هزارمین"); // -3000
wordsToNumber("منفی سه هزارم"); // -3000
wordsToNumber("منفی سه هزار"); // -3000
wordsToNumber("سه هزار دویست و دوازده"); // 3212
wordsToNumber("دوازده هزار بیست دو"); // 12022- Digits converter
wordsToNumber("منفی سه هزارمین", { digits: "fa" }); // "-۳۰۰۰"
wordsToNumber("دوازده هزار بیست دو", { digits: "fa" }); // ۱۲۰۲۲- Add commas
wordsToNumber("منفی سه هزارمین", { addCommas: true }); // "-3,000"
wordsToNumber("دوازده هزار بیست دو", { addCommas: true }); // "12,022"- Fuzzy typo fixer(
v1.5.0):
import { WordsToNumber } from "@persian-tools/persian-tools";
wordsToNumber("یگصد و بنجاه هزار", { fuzzy: true }); // "150000"
wordsToNumber("دویشت ر بیشت هزار", { fuzzy: true }); // "220000"
wordsToNumber("منقی ضد", { fuzzy: true }); // "-100"import { numberToWords } from "@persian-tools/persian-tools";
numberToWords(500443); // "پانصد هزار و چهار صد و چهل و سه"
numberToWords("500,443"); // "پانصد هزار و چهار صد و چهل و سه"
numberToWords("500,443", { ordinal: true }); // "پانصد هزار و چهار صد و چهل و سوم"
numberToWords(30000000000); // "سی میلیارد"NOTE: This function supports the largest safe integer (9007199254740991 / 2^53 - 1)
import { addCommas, removeCommas } from "@persian-tools/persian-tools";
addCommas(30000000); // "30,000,000"
removeCommas("30,000,000"); // 30000000import {
digitsArToFa,
digitsArToEn,
digitsEnToFa,
digitsFaToEn,
digitsEnToAr,
digitsFaToAr,
} from "@persian-tools/persian-tools";
digitsArToFa("۸۹123۴۵"); // "۸۹123۴۵"
digitsArToEn("٨٩123٤٥"); // "8912345"
digitsEnToFa("123۴۵۶"); // "۱۲۳۴۵۶"
digitsEnToAr("123٤٥٦"); // "۱۲۳٤٥٦"
digitsFaToAr("۱۷۸۲۳۴۰۵۶۹"); // ١٧٨٢٣٤٠٥٦٩import { verifyIranianNationalId, getPlaceByIranNationalId } from "@persian-tools/persian-tools";
verifyIranianNationalId("0499370899"); // true
verifyIranianNationalId("0684159415"); // falseimport { verifyIranianLegalId } from "@persian-tools/persian-tools";
verifyIranianLegalId(10380285692); // false
verifyIranianLegalId(10380284790); // truegetPlaceByIranNationalId("0084575948").city; // "تهران مرکزی"import { verifyCardNumber, getBankNameFromCardNumber } from "@persian-tools/persian-tools";
verifyCardNumber(6037701689095443); // true
getBankNameFromCardNumber("6219861034529007"); // "بانک سامان"Validate the correctness of the text of the Persian language and clear the Arabic letters in the Persian text.
import { isPersian, hasPersian, toPersianChars } from "@persian-tools/persian-tools";
isPersian("این یک متن فارسی است؟"); // true
isPersian("Lorem Ipsum Test"); // false
isPersian("هل هذا نص فارسي؟"); // false
hasPersian("This text includes فارسی"); // true
toPersianChars("علي"); // علیNote: You can pass 2 more options to isPersian to customize it as your needs:
isComplex: If you passtrue, Then it accepts some of regular arabic characters which are commons in persian texts.(default isfalse)trimPattern: By default the function skips some of characters e.g."'-+()؟.andwhitespaces. You can pass your own customizedregexas you need.
import { URLfix } from "@persian-tools/persian-tools";
URLfix(
"https://fa.wikipedia.org/wiki/%D9%85%D8%AF%DB%8C%D8%A7%D9%88%DB%8C%DA%A9%DB%8C:Gadget-Extra-Editbuttons-botworks.js",
); // "https://fa.wikipedia.org/wiki/مدیاویکی:Gadget-Extra-Editbuttons-botworks.js"
URLfix("https://en.wikipedia.org/wiki/Persian_alphabet"); // "https://en.wikipedia.org/wiki/Persian_alphabet",
URLfix("Sample Text"); // "Sample Text"| Method | Description | Return type |
|---|---|---|
getResult |
Result of bill calculated information | BillResult |
getAmount |
Calculate Bill amount by payment id and bill id which entered by the Bill constructor | number |
getBillType |
Get Bill provider type name | BillTypes |
getBarcode |
Calculate and get Bill's barcode | string |
verificationBill |
Validate entered both Bill id and payment id, and return true if bill id and payment id relation was true | boolean |
verificationBillId |
Validate entered Bill id | boolean |
verificationBillPayment |
Validate entered Bill payment id | boolean |
import { Bill } from "@persian-tools/persian-tools";
// Calculate bill amount by bill id and payment id
// Convert to Iranian Rials
// Return bill amount by Toman(Iranian currency type) by default
new Bill({ billId: 1117753200140, paymentId: 12070160, currency: "rial" }).getResult().amount; // 120000
// Find Bill's type by bill id and payment id
new Bill({ billId: 7748317800142, paymentId: 1770160 }).getResult().type; // تلفن ثابت
new Bill({ billId: 9174639504124, paymentId: 12908197 }).getResult().type; // برق
new Bill({ billId: 2050327604613, paymentId: 1070189 }).getResult().type; // آب
new Bill({ billId: 9100074409151, paymentId: 12908190 }).getResult().type; // تلفن همراه
new Bill({ billId: 7748317800105, paymentId: 1770160 }).getResult().type; // unknown
// Check Bill id validation
new Bill({ billId: 7748317800142, paymentId: 1770160 }).getResult().isValidBillId; // true
new Bill({ billId: 2234322344613, paymentId: 1070189 }).getResult().isValidBillId; // false
// Check Bill's payment id validation
new Bill({ billId: 7748317800142, paymentId: 1770160 }).getResult().isValidBillPayment; // true
new Bill({ billId: 9174639504124, paymentId: 12908197 }).getResult().isValidBillPayment; // false
// Check Bill id and payment id relations which is valid or not
new Bill({ billId: 7748317800142, paymentId: 1770160 }).getResult().isValid; // true
new Bill({ billId: 2234322344613, paymentId: 1070189 }).getResult().isValid; // false
// Get barcode from billId and paymentId
new Bill({ billId: 7748317800142, paymentId: 1770160 }).getResult().barcode; // 77483178001420001770160
new Bill({ billId: 9174639504124, paymentId: 12908197 }).getResult().barcode; // 917463950412400012908197
// Get bill bill id and payment id by bill's barcode
new Bill({ barcode: "22343223446130001070189" }).findByBarcode(); // { billId: 2234322344613 , paymentId: 1070189 }- Check validation
import { isShebaValid } from "@persian-tools/persian-tools";
isShebaValid("IR820540102680020817909002"); // true
isShebaValid("IR01234567890123456789"); // false- Recognize bank information
import { getShebaInfo } from "@persian-tools/persian-tools";
getShebaInfo("IR820540102680020817909002");
/*
Result: {
"nickname": "parsian",
"name": "Parsian Bank",
"persianName": "بانک پارسیان",
"code": "054",
"accountNumberAvailable": true,
"accountNumber": "020817909002",
"formattedAccountNumber": "002-00817909-002"
}
*/import { halfSpace } from "@persian-tools/persian-tools";
halfSpace("نمی خواهی درخت ها را ببینیم؟"); // "نمی‌خواهی درخت‌ها را ببینیم؟"| Properties | Description | Return type |
|---|---|---|
info |
provide info about plate | PlateResultApi |
isValid |
checks if plate is valid or not | boolean |
Usage
import { Plate } from "@persian-tools/persian-tools";
Plate("12D45147"); // passing string argument
// or passing in object style
Plate({
number: "1245147",
char: "الف",
});- Getting info about plate
import { Plate } from "@persian-tools/persian-tools";
Plate("12D45147").info;
/*
{
template: 12 D 451 ایران 47
province: مرکزی ,
type: Car,
category: دیپلمات,
details: {
firstTwoDigits: 12,
plateCharacter: D,
nextThreeDigits: 451,
provinceCode: 47
}
}
*/
// handle motorcyles plate
Plate(12345678).info;
/*
{
template: 123-45678,
province: مرکز تهران,
type: Motorcyle,
category: null,
details: {
digits: 45678
provinceCode:123
}
}
*/Plates that have farsi digits in them(like: الف، ب، ص) will be returned in this template
${first_two_digits}${plate_character}${next_three_digits}ایران${province_code}
- Checking if plate is valid
import { Plate } from "@persian-tools/persian-tools";
Plate("12D45147").isValid;
/*
true
*/
Plate(12345678).isValid;
/*
true
*/
Plate(1234567).isValid;
/*
will return false - plate character is not provided
*/
Plate(1204567).isValid;
/*
will return false - plate can't have 0 in its digits (except last digit)
*/Usage
Suppose the current time is equal to
1400/03/17 18:00:00
import { timeAgo } from "@persian-tools/persian-tools";
// Previous
timeAgo("1400/03/17 17:55:00"); // 5 دقیقه قبل
timeAgo("1400/02/17 18:00:00"); // حدود 1 ماه قبل
// Next
timeAgo("1400/04/07 18:00:00"); // حدود 3 هفته بعد
timeAgo("1401/03/17 18:00:00"); // حدود 1 سال بعدUsage
Takes a date(it could be string, number or date) and calculate years, months, days, hours, minutes and seconds remained to that specific date.
import { remainingTime } from "@persian-tools/persian-tools";
remainingTime("2023-05-14T13:35:59Z").toString(); // ۱ سال و ۱ ماه و ۲ روز و ۳ ساعت و ۵ دقیقه و ۸ ثانیه
const { years, months, days, hours, minutes, seconds, isFinished } = remainingTime("2023-05-14T13:35:59Z");
years; // 1
minutes; // 5
isFinished; // false
remainingTime("2018-04-12T10:30:51Z").isFinished; // trueUsage
- Finding information such as province, type and model of phone number
import { phoneNumberDetail } from "@persian-tools/persian-tools";
phoneNumberDetail("9123456789");
/*
{
province: ["البرز", "زنجان", "سمنان", "قزوین", "قم", "برخی از شهرستان های استان مرکزی"],
base: "تهران",
operator: "همراه اول",
type: ["permanent"],
}
*/
phoneNumberDetail("09022002580");
/*
{
province: [],
base: "کشوری",
operator: "ایرانسل",
type: ["permanent", "credit"],
}
*/
phoneNumberDetail("09981000000");
/*
{
province: [],
base: "کشوری",
operator: "شاتل موبایل",
type: ["credit"],
}
*/- Validating phone number
import { phoneNumberValidator } from "@persian-tools/persian-tools";
phoneNumberValidator("09122002580"); // true
phoneNumberValidator("09192002580"); // true
phoneNumberValidator("+989022002580"); // true
phoneNumberValidator("09022002580"); // true
phoneNumberValidator("989022002580"); // true
phoneNumberValidator("00989022002580"); // true
phoneNumberValidator("9022002580"); // true
phoneNumberValidator("09802002580"); // false- Normalizing phone number
import { phoneNumberNormalizer } from "@persian-tools/persian-tools";
phoneNumberNormalizer("+989022002580", "0"); // 09022002580
phoneNumberNormalizer("989022002580", "0"); // 09022002580
phoneNumberNormalizer("09022002580", "0"); // 09022002580
phoneNumberNormalizer("09022002580", "+98"); // +989022002580Usage
This function returns the Capital City name by its state name. if it can't find anything, it will throws an error.
import { findCapitalByProvince } from "@persian-tools/persian-tools";
findCapitalByProvince("خراسان رضوی"); // مشهد
findCapitalByProvince("آذربایجان شرقی"); // تبریز
// this throw an error string 'no province found'
findCapitalByProvince("دبی");- Write Jalaali and Gregorian functions to convert Date together.
Thank you for your interest in contributing! Please feel free to put up a PR for any issue or feature request.
This project is licensed under the MIT License - see the LICENSE.md file for details.
 Bank Maskan |
 MyDong |
 Melkba |
If you're curious to see what can be accomplished with Persian tools, check out these apps!
If you have a software you'd like to see added, please open a pull request! All that's required is a name, link, and a PNG icon.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
![allcontributors[bot] avatar](https://avatars.githubusercontent.com/in/23186?v=4 "allcontributors[bot]")
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "github-actions[bot]")
![renovate[bot] avatar](https://avatars.githubusercontent.com/in/2740?v=4 "renovate[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent