tamil-number

Convert integer numbers into natural Tamil words with zero runtime dependencies.

toTamilNumber(123);
// "நூற்று இருபத்து மூன்று"

tamil-number implements the actual Tamil number-naming grammar (சந்தி / word-fusion rules) instead of mechanically translating English number words — so compound numbers come out the way a Tamil speaker actually says them, e.g. 25 is இருபத்தைந்து, not இருபது ஐந்து.

Installation

npm install tamil-number

Usage

import { toTamilNumber } from "tamil-number";

console.log(toTamilNumber(123));
// நூற்று இருபத்து மூன்று

console.log(toTamilNumber(100000));
// ஒரு லட்சம்

console.log(toTamilNumber(12.5));
// பன்னிரண்டு புள்ளி ஐந்து

console.log(toTamilNumber(12345678901234567890n));
// bigint input is supported without precision loss

Negative numbers

Negative numbers use the proper Tamil mathematical term எதிர்மறை ("negative"), never மைனஸ் (a transliteration of the English "minus"):

toTamilNumber(-25);
// எதிர்மறை இருபத்தைந்து

toTamilNumber(-1000);
// எதிர்மறை ஆயிரம்

The negative form is always எதிர்மறை + <positive number in words>.

Decimal numbers

Decimal numbers are read the way Tamil speakers actually say them: the integer part in full, then புள்ளி ("point"), then each digit after the decimal point read individually:

toTamilNumber(12.5);
// பன்னிரண்டு புள்ளி ஐந்து

toTamilNumber(100.25);
// நூறு புள்ளி இரண்டு ஐந்து

toTamilNumber(-3.14);
// எதிர்மறை மூன்று புள்ளி ஒன்று நான்கு

Decimals are never rounded or truncated. Values requiring scientific notation to represent precisely (e.g. 1e-21) throw a RangeError instead of an inaccurate result.

Examples

| Input | Output | | --- | --- | | 0 | பூஜ்ஜியம் | | 1 | ஒன்று | | 5 | ஐந்து | | 9 | ஒன்பது | | 10 | பத்து | | 11 | பதினொன்று | | 12 | பன்னிரண்டு | | 15 | பதினைந்து | | 19 | பத்தொன்பது | | 20 | இருபது | | 21 | இருபத்து ஒன்று | | 22 | இருபத்திரண்டு | | 25 | இருபத்தைந்து | | 30 | முப்பது | | 42 | நாற்பத்திரண்டு | | 55 | ஐம்பத்தைந்து | | 99 | தொண்ணூற்றொன்பது | | 100 | நூறு | | 101 | நூற்று ஒன்று | | 123 | நூற்று இருபத்து மூன்று | | 200 | இருநூறு | | 999 | தொள்ளாயிரத்து தொண்ணூற்றொன்பது | | 1000 | ஆயிரம் | | 1001 | ஆயிரத்து ஒன்று | | 2000 | இரண்டாயிரம் | | 5000 | ஐயாயிரம் | | 9999 | ஒன்பதாயிரத்து தொள்ளாயிரத்து தொண்ணூற்றொன்பது | | 100000 | ஒரு லட்சம் | | 123456 | ஒரு லட்சம் இருபத்து மூன்றாயிரத்து நானூற்று ஐம்பத்தாறு | | 999999 | ஒன்பது லட்சம் தொண்ணூற்றொன்பதாயிரத்து தொள்ளாயிரத்து தொண்ணூற்றொன்பது | | 10000000 | ஒரு கோடி | | 12345678 | ஒரு கோடி இருபத்து மூன்று லட்சம் நாற்பத்தைந்தாயிரத்து அறுநூற்று எழுபத்தெட்டு | | 99999999 | தொண்ணூற்றொன்பது கோடி தொண்ணூற்றொன்பது லட்சம் தொண்ணூற்றொன்பதாயிரத்து தொள்ளாயிரத்து தொண்ணூற்றொன்பது | | -1 | எதிர்மறை ஒன்று | | -25 | எதிர்மறை இருபத்தைந்து | | -123 | எதிர்மறை நூற்று இருபத்து மூன்று | | -100000 | எதிர்மறை ஒரு லட்சம் | | 12.5 | பன்னிரண்டு புள்ளி ஐந்து | | 0.1 | பூஜ்ஜியம் புள்ளி ஒன்று | | 100.25 | நூறு புள்ளி இரண்டு ஐந்து | | -3.14 | எதிர்மறை மூன்று புள்ளி ஒன்று நான்கு |

Supported input

• Integers (number), including 0 and negative integers.
• Decimal numbers (number), read as <integer part> புள்ளி <digits>.
• bigint, for values beyond Number.MAX_SAFE_INTEGER — bigints are never converted through number, so there is no precision loss.
• The Indian numbering system is used throughout: ஆயிரம் (thousand), லட்சம் (lakh, 10⁵) and கோடி (crore, 10⁷) — never million/billion.
• Magnitudes are supported up to (but excluding) 10²¹. Values at or beyond that magnitude throw a RangeError instead of returning an incorrect or misleading result.

Invalid input

toTamilNumber never silently rounds, truncates, or guesses. It throws for:

toTamilNumber(NaN); // TypeError
toTamilNumber(Infinity); // RangeError
toTamilNumber(-Infinity); // RangeError
toTamilNumber(1e-21); // RangeError — requires scientific notation
toTamilNumber(Number.MAX_SAFE_INTEGER + 10); // RangeError — use bigint instead

Linguistic conventions

Tamil number words are not a simple concatenation of hundreds + tens + ones. This library encodes the real sandhi (word-fusion) rules, for example:

• நூறு (100) becomes நூற்று when followed by a remainder: நூற்று ஒன்று (101).
• ஆயிரம் (1000) becomes ஆயிரத்து the same way: ஆயிரத்து நூறு (1100).
• இருபது (20) + இரண்டு (2) fuses into இருபத்திரண்டு (22), while இருபது + ஒன்று stays as two words: இருபத்து ஒன்று (21).
• ஒன்று becomes the adjectival ஒரு before லட்சம்/கோடி: ஒரு லட்சம், ஒரு கோடி (never ஒன்று லட்சம்).
• For magnitudes beyond one crore, the number is expressed by recursively composing கோடி (e.g. 100,00,00,000 → நூறு கோடி, and 10,00,00,00,00,000 → ஒரு லட்சம் கோடி), which mirrors how very large numbers are conventionally read aloud in modern Tamil.
• Decimal digits after புள்ளி are read one at a time (12.34 → பன்னிரண்டு புள்ளி மூன்று நான்கு, not "முப்பத்து நான்கு"), matching how precise decimal values are conventionally read aloud.

Zero dependencies

Zero runtime dependencies. The published package ships only compiled JavaScript and type declarations.

Samples

Runnable example scripts live in samples/. After cloning the repo and running npm install:

npm run samples

This runs every sample in samples/index.ts in order. A single sample can also be run directly, e.g.:

npx tsx samples/03-lakhs-and-crores.ts

Scope

Version 1 does exactly one thing: number → natural Tamil words. It does not implement currency formatting, the Tamil calendar, a CLI, or any UI/framework bindings.

Future scope

These are explicitly out of scope for v1 but may be considered for future versions:

• Tamil Unicode numerals (e.g. ௧௨௩).
• Tamil → number parsing (the reverse of toTamilNumber).
• Dates expressed in Tamil words.

License

MIT