n2words 1.23.1 → 2.0.0

package/lib/languages/uk.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Ukrainian language converter.
+ *
+ * Supports:
+ * - Three-form pluralization (one/few/many)
+ * - Gender agreement (один/одна, два/дві)
+ * - Ukrainian orthography and phonology
+ */
+export class Ukrainian extends SlavicLanguage {
+    onesWords: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    onesFeminineWords: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    teensWords: {
+        0: string;
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    twentiesWords: {
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    hundredsWords: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+    };
+    pluralForms: {
+        1: string[];
+        2: string[];
+        3: string[];
+        4: string[];
+        5: string[];
+        6: string[];
+        7: string[];
+        8: string[];
+        9: string[];
+        10: string[];
+    };
+    /**
+     * Ukrainian thousands (тисяча) are feminine, requiring одна/двi forms.
+     * Other scales (million, billion, etc.) are masculine.
+     */
+    scaleGenders: {
+        1: boolean;
+    };
+}
+import { SlavicLanguage } from '../classes/slavic-language.js';

package/lib/{i18n → languages}/uk.js

@@ -1,7 +1,19 @@
-import { N2WordsRU } from './ru.js';
+import { SlavicLanguage } from '../classes/slavic-language.js'
 
-export class N2WordsUK extends N2WordsRU {
-  ones = {
+/**
+ * Ukrainian language converter.
+ *
+ * Supports:
+ * - Three-form pluralization (one/few/many)
+ * - Gender agreement (один/одна, два/дві)
+ * - Ukrainian orthography and phonology
+ */
+export class Ukrainian extends SlavicLanguage {
+  negativeWord = 'мiнус'
+  decimalSeparatorWord = 'кома'
+  zeroWord = 'нуль'
+
+  onesWords = {
     1: 'один',
     2: 'два',
     3: 'три',
@@ -11,9 +23,9 @@ export class N2WordsUK extends N2WordsRU {
     7: 'сiм',
     8: 'вiсiм',
     9: 'дев\'ять'
-  };
+  }
 
-  onesFeminine = {
+  onesFeminineWords = {
     1: 'одна',
     2: 'двi',
     3: 'три',
@@ -23,9 +35,9 @@ export class N2WordsUK extends N2WordsRU {
     7: 'сiм',
     8: 'вiсiм',
     9: 'дев\'ять'
-  };
+  }
 
-  tens = {
+  teensWords = {
     0: 'десять',
     1: 'одинадцять',
     2: 'дванадцять',
@@ -36,9 +48,9 @@ export class N2WordsUK extends N2WordsRU {
     7: 'сiмнадцять',
     8: 'вiсiмнадцять',
     9: 'дев\'ятнадцять'
-  };
+  }
 
-  twenties = {
+  twentiesWords = {
     2: 'двадцять',
     3: 'тридцять',
     4: 'сорок',
@@ -47,9 +59,9 @@ export class N2WordsUK extends N2WordsRU {
     7: 'сiмдесят',
     8: 'вiсiмдесят',
     9: 'дев\'яносто'
-  };
+  }
 
-  hundreds = {
+  hundredsWords = {
     1: 'сто',
     2: 'двiстi',
     3: 'триста',
@@ -59,9 +71,9 @@ export class N2WordsUK extends N2WordsRU {
     7: 'сiмсот',
     8: 'вiсiмсот',
     9: 'дев\'ятсот'
-  };
+  }
 
-  thousands = {
+  pluralForms = {
     1: ['тисяча', 'тисячi', 'тисяч'], // 10^ 3
     2: ['мiльйон', 'мiльйони', 'мiльйонiв'], // 10^ 6
     3: ['мiльярд', 'мiльярди', 'мiльярдiв'], // 10^ 9
@@ -71,25 +83,14 @@ export class N2WordsUK extends N2WordsRU {
     7: ['секстильйон', 'секстильйони', 'секстильйонiв'], // 10^ 21
     8: ['септильйон', 'септильйони', 'септильйонiв'], // 10^ 24
     9: ['октильйон', 'октильйони', 'октильйонiв'], // 10^ 27
-    10: ['нонiльйон', 'нонiльйони', 'нонiльйонiв'], // 10^ 30
-  };
-
-  constructor(options) {
-    super(Object.assign({
-      negativeWord: 'мiнус',
-      separatorWord: 'кома',
-      zero: 'нуль'
-    }, options));
+    10: ['нонiльйон', 'нонiльйони', 'нонiльйонiв'] // 10^ 30
   }
-}
 
-/**
- * Converts a value to cardinal (written) form.
- * @param {number|string|bigint} value Number to be convert.
- * @param {object} [options] Options for class.
- * @returns {string} Value in cardinal (written) format.
- * @throws {Error} Value cannot be invalid.
- */
-export default function floatToCardinal (value, options = {}) {
-  return new N2WordsUK(options).floatToCardinal(value);
+  /**
+   * Ukrainian thousands (тисяча) are feminine, requiring одна/двi forms.
+   * Other scales (million, billion, etc.) are masculine.
+   */
+  scaleGenders = {
+    1: true // thousands are feminine
+  }
 }

package/lib/languages/ur.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Urdu language converter.
+ *
+ * Supports:
+ * - Indian numbering system (ہزار, لاکھ, کروڑ)
+ * - Urdu script (right-to-left)
+ * - Complete word forms for 0-99
+ */
+export class Urdu extends SouthAsianLanguage {
+}
+import { SouthAsianLanguage } from '../classes/south-asian-language.js';

package/lib/languages/ur.js

@@ -0,0 +1,131 @@
+import { SouthAsianLanguage } from '../classes/south-asian-language.js'
+
+/**
+ * Urdu language converter.
+ *
+ * Supports:
+ * - Indian numbering system (ہزار, لاکھ, کروڑ)
+ * - Urdu script (right-to-left)
+ * - Complete word forms for 0-99
+ */
+export class Urdu extends SouthAsianLanguage {
+  negativeWord = 'منفی'
+  decimalSeparatorWord = 'اعشاریہ'
+  zeroWord = 'صفر'
+  hundredWord = 'سو'
+
+  belowHundredWords = [
+    'صفر',
+    'ایک',
+    'دو',
+    'تین',
+    'چار',
+    'پانچ',
+    'چھ',
+    'سات',
+    'آٹھ',
+    'نو',
+    'دس',
+    'گیارہ',
+    'بارہ',
+    'تیرہ',
+    'چودہ',
+    'پندرہ',
+    'سولہ',
+    'سترہ',
+    'اٹھارہ',
+    'انیس',
+    'بیس',
+    'اکیس',
+    'بائیس',
+    'تیئیس',
+    'چوبیس',
+    'پچیس',
+    'چھبیس',
+    'ستائیس',
+    'اٹھائیس',
+    'انتیس',
+    'تیس',
+    'اکتیس',
+    'بتیس',
+    'تینتیس',
+    'چونتیس',
+    'پینتیس',
+    'چھتیس',
+    'سینتیس',
+    'اڑتیس',
+    'انتالیس',
+    'چالیس',
+    'اکتالیس',
+    'بیالیس',
+    'تینتالیس',
+    'چوالیس',
+    'پینتالیس',
+    'چھالیس',
+    'سینتالیس',
+    'اڑتالیس',
+    'انچاس',
+    'پچاس',
+    'اکاون',
+    'باون',
+    'ترپن',
+    'چون',
+    'پچپن',
+    'چھپن',
+    'ستاون',
+    'اٹھاون',
+    'انسٹھ',
+    'ساٹھ',
+    'اکسٹھ',
+    'باسٹھ',
+    'ترسٹھ',
+    'چونسٹھ',
+    'پینسٹھ',
+    'چھیاسٹھ',
+    'سڑسٹھ',
+    'اڑسٹھ',
+    'انہتر',
+    'ستر',
+    'اکہتر',
+    'بہتر',
+    'تہتر',
+    'چوہتر',
+    'پچھتر',
+    'چھہتر',
+    'ستتر',
+    'اٹھہتر',
+    'اناسی',
+    'اسی',
+    'اکیاسی',
+    'بیاسی',
+    'تریاسی',
+    'چوراسی',
+    'پچاسی',
+    'چھیاسی',
+    'ستاسی',
+    'اٹھاسی',
+    'نواسی',
+    'نوے',
+    'اکانوے',
+    'بانوے',
+    'ترانوے',
+    'چورانوے',
+    'پچانوے',
+    'چھیانوے',
+    'ستانوے',
+    'اٹھانوے',
+    'ننانوے'
+  ]
+
+  scaleWords = [
+    '',
+    'ہزار',
+    'لاکھ',
+    'کروڑ',
+    'ارب',
+    'کھرب',
+    'نیل',
+    'پدم',
+    'شنکھ'
+  ]
+}

package/lib/{i18n → languages}/vi.d.ts

@@ -1,14 +1,13 @@
 /**
- * Converts a value to cardinal (written) form.
- * @param {number|string|bigint} value Number to be convert.
- * @param {object} [options] Options for class.
- * @returns {string} Value in cardinal (written) format.
- * @throws {Error} Value cannot be invalid.
+ * Vietnamese language converter.
+ *
+ * Supports:
+ * - Special pronunciation rules (lăm for 5, mốt for final 1)
+ * - "Lẻ" (odd/extra) when tens place is zero
+ * - Vietnamese diacritical marks
  */
-export default function floatToCardinal(value: number | string | bigint, options?: object): string;
-export class N2WordsID extends AbstractLanguage {
-    constructor(options: any);
-    base: {
+export class Vietnamese extends AbstractLanguage {
+    belowTwentyWords: {
         0: string;
         1: string;
         2: string;
@@ -30,7 +29,7 @@ export class N2WordsID extends AbstractLanguage {
         18: string;
         19: string;
     };
-    tens: {
+    twentiesWords: {
         20: string;
         30: string;
         40: string;
@@ -40,7 +39,7 @@ export class N2WordsID extends AbstractLanguage {
         80: string;
         90: string;
     };
-    thousands: {
+    scaleWords: {
         1: string;
         2: string;
         3: string;
@@ -62,9 +61,12 @@ export class N2WordsID extends AbstractLanguage {
         19: string;
         20: string;
     };
+    /** Convert numbers less than 100 to Vietnamese words. */
     convertLess100(number: any): any;
+    /** Convert numbers less than 1000 to Vietnamese words. */
     convertLess1000(number: any): any;
+    /** Convert numbers greater than 1000 to Vietnamese words. */
     convertMore1000(number: any): any;
-    toCardinal(number: any): any;
+    integerToWords(integerPart: any): any;
 }
-import AbstractLanguage from '../classes/abstract-language.js';
+import { AbstractLanguage } from '../classes/abstract-language.js';

package/lib/languages/vi.js

@@ -0,0 +1,147 @@
+import { AbstractLanguage } from '../classes/abstract-language.js'
+
+/**
+ * Vietnamese language converter.
+ *
+ * Supports:
+ * - Special pronunciation rules (lăm for 5, mốt for final 1)
+ * - "Lẻ" (odd/extra) when tens place is zero
+ * - Vietnamese diacritical marks
+ */
+export class Vietnamese extends AbstractLanguage {
+  negativeWord = 'âm'
+  decimalSeparatorWord = 'phẩy'
+  zeroWord = 'không'
+
+  belowTwentyWords = {
+    0: 'không',
+    1: 'một',
+    2: 'hai',
+    3: 'ba',
+    4: 'bốn',
+    5: 'năm',
+    6: 'sáu',
+    7: 'bảy',
+    8: 'tám',
+    9: 'chín',
+    10: 'mười',
+    11: 'mười một',
+    12: 'mười hai',
+    13: 'mười ba',
+    14: 'mười bốn',
+    15: 'mười lăm',
+    16: 'mười sáu',
+    17: 'mười bảy',
+    18: 'mười tám',
+    19: 'mười chín'
+  }
+
+  twentiesWords = {
+    20: 'hai mươi',
+    30: 'ba mươi',
+    40: 'bốn mươi',
+    50: 'năm mươi',
+    60: 'sáu mươi',
+    70: 'bảy mươi',
+    80: 'tám mươi',
+    90: 'chín mươi'
+  }
+
+  scaleWords = {
+    1: 'nghìn', // 10^1
+    2: 'triệu', // 10^2
+    3: 'tỷ', // 10^3
+    4: 'nghìn tỷ',
+    5: 'trăm nghìn tỷ',
+    6: 'Quintillion',
+    7: 'Sextillion',
+    8: 'Septillion',
+    9: 'Octillion',
+    10: 'Nonillion',
+    11: 'Decillion',
+    12: 'Undecillion',
+    13: 'Duodecillion',
+    14: 'Tredecillion',
+    15: 'Quattuordecillion',
+    16: 'Sexdecillion',
+    17: 'Septendecillion',
+    18: 'Octodecillion',
+    19: 'Novemdecillion',
+    20: 'Vigintillion'
+  }
+
+  /** Convert numbers less than 100 to Vietnamese words. */
+  convertLess100 (number) {
+    const unitsPart = number % 10
+    const tensPart = number - unitsPart
+    const tensPartText = this.twentiesWords[tensPart]
+    if (unitsPart === 0) {
+      return tensPartText
+    }
+    const unitsPartText = this.belowTwentyWords[unitsPart]
+    let suffix = unitsPartText
+    if (unitsPart === 1) {
+      suffix = 'mốt'
+    }
+    if (unitsPart === 5) {
+      suffix = 'lăm'
+    }
+    return tensPartText + ' ' + suffix
+  }
+
+  /** Convert numbers less than 1000 to Vietnamese words. */
+  convertLess1000 (number) {
+    const words = []
+    const tensUnitsPart = number % 100
+    const hundredsPart = number - tensUnitsPart
+    if (hundredsPart > 0) {
+      words.push(this.belowTwentyWords[hundredsPart / 100], 'trăm')
+    }
+    if (tensUnitsPart > 0 && tensUnitsPart < 10) {
+      if (words.length > 0) {
+        words.push('lẻ')
+      }
+      if (tensUnitsPart === 5) {
+        words.push('năm')
+      } else {
+        words.push(this.belowTwentyWords[tensUnitsPart])
+      }
+    }
+    if (tensUnitsPart >= 10) {
+      words.push(this.integerToWords(tensUnitsPart))
+    }
+    return words.join(' ')
+  }
+
+  /** Convert numbers greater than 1000 to Vietnamese words. */
+  convertMore1000 (number) {
+    const words = []
+    let division = number / 1000n
+    let power = 1
+    while (division >= 1000n) {
+      division = division / 1000n
+      power = power + 1
+    }
+    const r = number - (division * BigInt(Math.pow(1000, power)))
+    words.push(this.integerToWords(division), this.scaleWords[power])
+    if (r > 0n) {
+      if (r <= 99n) {
+        words.push('lẻ')
+      }
+      words.push(this.integerToWords(r))
+    }
+    return words.join(' ')
+  }
+
+  integerToWords (integerPart) {
+    if (integerPart < 20n) {
+      return this.belowTwentyWords[Number(integerPart)]
+    } else {
+      if (integerPart < 100n) {
+        return this.convertLess100(Number(integerPart))
+      } else {
+        return (integerPart < 1000n ? this.convertLess1000(Number(integerPart)) : this.convertMore1000(integerPart))
+      }
+    }
+  }
+}

package/lib/languages/zh-Hans.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Simplified Chinese language converter.
+ *
+ * Supports:
+ * - Simplified Chinese characters (简体中文)
+ * - No word separators (concatenated format)
+ * - Optional formal (financial) vs common numerals
+ */
+export class SimplifiedChinese extends GreedyScaleLanguage {
+    constructor(options?: {});
+    scaleWords: (string | bigint)[][];
+    /** Combines two word-sets according to Chinese grammar rules. */
+    combineWordSets(preceding: any, following: any): any;
+    /** Returns the number of digits in a number. */
+    digit(number_: any): any;
+    /** Counts the number of zero digits in a number. */
+    zeroDigit(number_: any): number;
+    /** Converts decimal digits to words by reading each digit individually. */
+    decimalDigitsToWords(decimalString: any): string[];
+}
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js';

package/lib/languages/zh-Hans.js

@@ -0,0 +1,111 @@
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js'
+
+/**
+ * Simplified Chinese language converter.
+ *
+ * Supports:
+ * - Simplified Chinese characters (简体中文)
+ * - No word separators (concatenated format)
+ * - Optional formal (financial) vs common numerals
+ */
+export class SimplifiedChinese extends GreedyScaleLanguage {
+  negativeWord = '负'
+  decimalSeparatorWord = '点'
+  zeroWord = '零'
+  wordSeparator = ''
+
+  constructor (options = {}) {
+    super()
+
+    this.setOptions({
+      formal: true
+    }, options)
+
+    if (this.options.formal) {
+      this.scaleWords = [
+        [1_000_000_000_000n, '万'],
+        [100_000_000n, '亿'],
+        [10_000n, '万'],
+        [1000n, '仟'],
+        [100n, '佰'],
+        [10n, '拾'],
+        [9n, '玖'],
+        [8n, '捌'],
+        [7n, '柒'],
+        [6n, '陆'],
+        [5n, '伍'],
+        [4n, '肆'],
+        [3n, '叁'],
+        [2n, '贰'],
+        [1n, '壹'],
+        [0n, '零']
+      ]
+    } else {
+      this.scaleWords = [
+        [1_000_000_000_000n, '万'],
+        [100_000_000n, '亿'],
+        [10_000n, '万'],
+        [1000n, '千'],
+        [100n, '百'],
+        [10n, '十'],
+        [9n, '九'],
+        [8n, '八'],
+        [7n, '七'],
+        [6n, '六'],
+        [5n, '五'],
+        [4n, '四'],
+        [3n, '三'],
+        [2n, '二'],
+        [1n, '一'],
+        [0n, '零']
+      ]
+    }
+  }
+
+  /** Combines two word-sets according to Chinese grammar rules. */
+  combineWordSets (preceding, following) {
+    const precedingWord = Object.keys(preceding)[0]
+    const precedingValue = Object.values(preceding)[0]
+    const followingWord = Object.keys(following)[0]
+    const followingValue = Object.values(following)[0]
+
+    // Implicit one: omit 1 before single digits (< 10)
+    if (precedingValue === 1n && followingValue < 10n) {
+      return following
+    }
+
+    // Multiply when following > preceding (scale words like 仁, 万, 亿)
+    if (followingValue > precedingValue) {
+      return { [`${precedingWord}${followingWord}`]: precedingValue * followingValue }
+    }
+
+    // Insert "零" (zero) when position skip levels (e.g., 1003 = 千零三)
+    // zeroDigit() checks if gap exists between preceding and following magnitude
+    if (this.zeroDigit(precedingValue) > this.digit(followingValue)) {
+      return { [`${precedingWord}${this.zeroWord}${followingWord}`]: precedingValue + followingValue }
+    }
+
+    // Default: concatenate without zero insertion
+    return { [`${precedingWord}${followingWord}`]: precedingValue + followingValue }
+  }
+
+  /** Returns the number of digits in a number. */
+  digit (number_) {
+    return number_.toString().length
+  }
+
+  /** Counts the number of zero digits in a number. */
+  zeroDigit (number_) {
+    return [...number_.toString()].filter(c => c === '0').length
+  }
+
+  /** Converts decimal digits to words by reading each digit individually. */
+  decimalDigitsToWords (decimalString) {
+    const words = []
+    for (let i = 0; i < decimalString.length; i++) {
+      const digitValue = BigInt(decimalString[i])
+      words.push(this.integerToWords(digitValue))
+    }
+    return words
+  }
+}

package/lib/languages/zh-Hant.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Traditional Chinese language converter.
+ *
+ * Supports:
+ * - Traditional Chinese characters (繁體中文)
+ * - No word separators (concatenated format)
+ * - Optional formal (financial) vs common numerals
+ */
+export class TraditionalChinese extends GreedyScaleLanguage {
+    constructor(options?: {});
+    scaleWords: (string | bigint)[][];
+    /** Combines two word-sets with Traditional Chinese grammar rules and zero insertion. */
+    combineWordSets(preceding: any, following: any): any;
+    /** Returns the number of digits in a number. */
+    digit(number_: any): any;
+    /** Counts the number of zero digits in a number. */
+    zeroDigit(number_: any): number;
+    /** Converts decimal digits to words by reading each digit individually. */
+    decimalDigitsToWords(decimalString: any): string[];
+}
+import { GreedyScaleLanguage } from '../classes/greedy-scale-language.js';