n2words 1.23.0 → 1.24.0

package/lib/languages/ar.js

@@ -0,0 +1,243 @@
+import AbstractLanguage from '../classes/abstract-language.js'
+
+/**
+ * @typedef {Object} ArabicOptions
+ * @property {string} [negativeWord='ناقص'] Word for negative numbers (minus).
+ * @property {boolean} [feminine=false] Use feminine forms for numbers.
+ */
+
+/**
+ * Arabic language converter.
+ *
+ * Converts numbers to Arabic words with full grammatical support:
+ * - Gender agreement (masculine/feminine forms)
+ * - Complex pluralization rules (singular, dual, plural forms)
+ * - Special handling for hundreds, thousands, millions, etc.
+ * - Right-to-left text orientation
+ * - Traditional Arabic number naming conventions
+ *
+ * Key Features:
+ * - Gender-aware number forms (واحد masculine vs واحدة feminine)
+ * - Dual forms: اثنان/اثنتان (two masculine/feminine)
+ * - Complex rule system for numbers 3-10 (requiring feminine when referring to countables)
+ * - Group-based algorithm: splits number by powers of 1000 (ones, thousands, millions, billions)
+ * - Tanween (nunation) for indefinite numbers
+ * - Sophisticated pluralization with singular, dual, and plural forms
+ *
+ * Algorithm:
+ * 1. Break number into groups of 3 digits (right to left)
+ * 2. For each non-zero group, convert to words using gender and plural rules
+ * 3. Append the appropriate magnitude word (ألف/مليون/مليار) with proper plural form
+ * 4. Join all groups with spaces
+ *
+ * Features:
+ * - Support for gender-aware number forms
+ * - Proper handling of Arabic dual forms (اثنان/اثنتان)
+ * - Complex group processing for large numbers
+ * - Right-to-left text orientation
+ * - Traditional Arabic number naming conventions
+ */
+export class Arabic extends AbstractLanguage {
+  decimalSeparatorWord = 'فاصلة'
+  zeroWord = 'صفر'
+  arabicTens = ['عشرون', 'ثلاثون', 'أربعون', 'خمسون', 'ستون', 'سبعون', 'ثمانون', 'تسعون']
+  arabicHundreds = ['', 'مائة', 'مئتان', 'ثلاثمائة', 'أربعمائة', 'خمسمائة', 'ستمائة', 'سبعمائة', 'ثمانمائة', 'تسعمائة']
+  arabicAppendedTwos = ['مئتا', 'ألفا', 'مليونا', 'مليارا', 'تريليونا', 'كوادريليونا', 'كوينتليونا', 'سكستيليونا']
+  arabicTwos = ['مئتان', 'ألفان', 'مليونان', 'ملياران', 'تريليونان', 'كوادريليونان', 'كوينتليونان', 'سكستيليونان']
+  arabicGroup = ['مائة', 'ألف', 'مليون', 'مليار', 'تريليون', 'كوادريليون', 'كوينتليون', 'سكستيليون']
+  arabicAppendedGroup = ['', 'ألفاً', 'مليوناً', 'ملياراً', 'تريليوناً', 'كوادريليوناً', 'كوينتليوناً', 'سكستيليوناً']
+  arabicPluralGroups = ['', 'آلاف', 'ملايين', 'مليارات', 'تريليونات', 'كوادريليونات', 'كوينتليونات', 'سكستيليونات']
+  ones = {
+    masculine: [
+      'واحد',
+      'اثنان',
+      'ثلاثة',
+      'أربعة',
+      'خمسة',
+      'ستة',
+      'سبعة',
+      'ثمانية',
+      'تسعة',
+      'عشرة',
+      'أحد عشر',
+      'اثنا عشر',
+      'ثلاثة عشر',
+      'أربعة عشر',
+      'خمسة عشر',
+      'ستة عشر',
+      'سبعة عشر',
+      'ثمانية عشر',
+      'تسعة عشر'
+    ],
+    feminine: [
+      'واحدة',
+      'اثنتان',
+      'ثلاث',
+      'أربع',
+      'خمس',
+      'ست',
+      'سبع',
+      'ثمان',
+      'تسع',
+      'عشر',
+      'إحدى عشرة',
+      'اثنتا عشرة',
+      'ثلاث عشرة',
+      'أربع عشرة',
+      'خمس عشرة',
+      'ست عشرة',
+      'سبع عشرة',
+      'ثماني عشرة',
+      'تسع عشرة'
+    ]
+  }
+
+  /**
+   * Initializes the Arabic converter with language-specific options.
+   *
+   * @param {ArabicOptions} [options={}] Configuration options.
+   */
+  constructor ({ negativeWord = 'ناقص', feminine = false } = {}) {
+    super()
+
+    this.feminine = feminine
+    this.negativeWord = negativeWord
+
+    this.selectedOnes = this.ones[this.feminine ? 'feminine' : 'masculine']
+  }
+
+  /**
+   * Returns the feminine status of a given digit (1-9).
+   *
+   * @param {number} digit - The digit to check (1-9).
+   * @returns {string} The word form of the digit based on feminine status.
+   */
+  digitFeminineStatus (digit) {
+    return this.selectedOnes[digit - 1]
+  }
+
+  /**
+   * Processes the Arabic group number and returns the corresponding Arabic representation.
+   * @param {number} groupNumber - The number to process. (Range: 1-999)
+   * @param {number} groupLevel - Group level to process. (See example)
+   * @returns {string} The Arabic representation of the group number.
+   * @example 12345678 is processed in blocks of 3: '678' (group 0), '345' (group 1), '12' (group 2).
+   */
+  processArabicGroup (groupNumber, groupLevel, fullNumber) {
+    const tens = groupNumber % 100
+    const hundredsRaw = groupNumber / 100
+    const hundreds = Math.trunc(hundredsRaw)
+    let returnValue = ''
+
+    // Process hundreds
+    if (hundreds > 0) {
+      if (tens === 0 && hundreds === 2) {
+        returnValue = this.arabicTwos[0]
+      } else {
+        const hundredsWord = this.arabicHundreds[hundreds]
+        if (hundredsWord) {
+          returnValue = hundredsWord
+          if (tens !== 0) {
+            returnValue += ' و'
+          }
+        }
+      }
+    }
+
+    // Process tens and ones
+    if (tens > 0) {
+      if (tens < 20) { // 1 -> 19
+        if (tens === 2 && hundreds === 0 && groupLevel > 0) {
+          // Cache expensive log10 calculation
+          const numValue = Number(fullNumber)
+          const pow = Math.trunc(Math.log10(numValue))
+          if (pow % 3 === 0 && fullNumber === BigInt(2 * Math.pow(10, pow))) {
+            returnValue = groupNumber === 2 ? this.arabicTwos[groupLevel] : this.arabicAppendedTwos[groupLevel]
+          } else {
+            returnValue = this.arabicTwos[groupLevel]
+          }
+        } else if (tens === 1 && groupLevel > 0) {
+          returnValue += this.arabicGroup[groupLevel]
+        } else {
+          returnValue += this.selectedOnes[tens - 1]
+        }
+      } else { // 20 -> 99
+        const ones = tens % 10
+        const tensIndex = Math.trunc(tens / 10) - 2
+
+        if (ones > 0) {
+          returnValue += this.selectedOnes[ones - 1]
+          returnValue += ' و'
+        }
+        returnValue += this.arabicTens[tensIndex]
+      }
+    }
+
+    return returnValue
+  }
+
+  /**
+   * Converts a number to its cardinal representation in Arabic.
+   * It process by blocks of 3 digits.
+   * @param {bigint} number - The number to convert.
+   * @returns {string} The cardinal representation of the number in Arabic.
+   */
+  convertWholePart (number) {
+    if (number === 0n) {
+      return this.zeroWord
+    }
+    let temp = number
+    let group = 0
+    let result = ''
+
+    // Process each group of 3 digits (right to left)
+    while (temp > 0n) {
+      const numberToProcess = Number(temp % 1000n)
+      temp = temp / 1000n
+
+      if (numberToProcess > 0) {
+        const groupDescription = this.processArabicGroup(numberToProcess, group, number)
+
+        if (groupDescription) {
+          // Add group name for thousands, millions, etc.
+          if (group > 0) {
+            if (result) {
+              result = ' و' + result
+            }
+
+            if (numberToProcess > 2) {
+              const remainder = numberToProcess % 100
+              if (remainder === 1) {
+                result = this.arabicGroup[group] + ' ' + result
+              } else if (numberToProcess >= 3 && numberToProcess <= 10) {
+                result = this.arabicPluralGroups[group] + ' ' + result
+              } else {
+                result = (result ? this.arabicAppendedGroup[group] : this.arabicGroup[group]) + ' ' + result
+              }
+            }
+          }
+
+          // Add group description (prepend for RTL)
+          result = groupDescription + ' ' + result
+        }
+      }
+
+      group++
+    }
+
+    return result.replace(/\s+/g, ' ').trim()
+  }
+}
+
+/**
+ * Converts a number to Arabic cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {ArabicOptions} [options={}] Configuration options.
+ * @returns {string} The number expressed in Arabic words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ */
+export default function convertToWords (value, options = {}) {
+  return new Arabic(options).convertToWords(value)
+}

package/lib/languages/az.js

@@ -0,0 +1,58 @@
+import TurkicLanguage from '../classes/turkic-language.js'
+
+/**
+ * Azerbaijani language converter.
+ *
+ * Inherits from TurkicLanguage shared patterns:
+ * - Space-separated number combinations
+ * - Omits '1' before hundreds and thousands
+ * - Supports flexible word spacing configuration
+ */
+export class Azerbaijani extends TurkicLanguage {
+  negativeWord = 'mənfi'
+  decimalSeparatorWord = 'nöqtə'
+  zeroWord = 'sıfır'
+  scaleWordPairs = [[1_000_000_000_000_000_000n, 'kentilyon'],
+    [1_000_000_000_000_000n, 'katrilyon'],
+    [1_000_000_000_000n, 'trilyon'],
+    [1_000_000_000n, 'milyar'],
+    [1_000_000n, 'milyon'],
+    [1000n, 'min'],
+    [100n, 'yüz'],
+    [90n, 'doxsan'],
+    [80n, 'səksən'],
+    [70n, 'yetmiş'],
+    [60n, 'altmış'],
+    [50n, 'əlli'],
+    [40n, 'qırx'],
+    [30n, 'otuz'],
+    [20n, 'iyirmi'],
+    [10n, 'on'],
+    [9n, 'doqquz'],
+    [8n, 'səkkiz'],
+    [7n, 'yeddi'],
+    [6n, 'altı'],
+    [5n, 'beş'],
+    [4n, 'dörd'],
+    [3n, 'üç'],
+    [2n, 'iki'],
+    [1n, 'bir'],
+    [0n, 'sıfır']]
+}
+
+/**
+ * Converts a number to Azerbaijani cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options] Conversion options (see AZ class).
+ * @returns {string} The number expressed in Azerbaijani words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ *
+ * @example
+ * convertToWords(42, { lang: 'az' }); // 'qırx iki'
+ * convertToWords(1000, { lang: 'az' }); // 'min'
+ */
+export default function convertToWords (value, options = {}) {
+  return new Azerbaijani(options).convertToWords(value)
+}

package/lib/languages/bn.js

@@ -0,0 +1,126 @@
+import SouthAsianLanguage from '../classes/south-asian-language.js'
+
+class Bengali extends SouthAsianLanguage {
+  negativeWord = 'মাইনাস'
+  decimalSeparatorWord = 'দশমিক'
+  zeroWord = 'শূন্য'
+  hundredWord = 'শত'
+  belowHundred = [
+    'শূন্য',
+    'এক',
+    'দুই',
+    'তিন',
+    'চার',
+    'পাঁচ',
+    'ছয়',
+    'সাত',
+    'আট',
+    'নয়',
+    'দশ',
+    'এগারো',
+    'বারো',
+    'তেরো',
+    'চৌদ্দ',
+    'পনেরো',
+    'ষোল',
+    'সতেরো',
+    'আঠারো',
+    'উনিশ',
+    'বিশ',
+    'একুশ',
+    'বাইশ',
+    'তেইশ',
+    'চব্বিশ',
+    'পঁচিশ',
+    'ছাব্বিশ',
+    'সাতাশ',
+    'আঠাশ',
+    'উনত্রিশ',
+    'ত্রিশ',
+    'একত্রিশ',
+    'বত্রিশ',
+    'তেত্রিশ',
+    'চৌত্রিশ',
+    'পঁয়ত্রিশ',
+    'ছত্রিশ',
+    'সাঁইত্রিশ',
+    'আটত্রিশ',
+    'উনচল্লিশ',
+    'চল্লিশ',
+    'একচল্লিশ',
+    'বেয়াল্লিশ',
+    'তেতাল্লিশ',
+    'চুয়াল্লিশ',
+    'পঁয়তাল্লিশ',
+    'ছেচল্লিশ',
+    'সাতচল্লিশ',
+    'আটচল্লিশ',
+    'উনপঞ্চাশ',
+    'পঞ্চাশ',
+    'একান্ন',
+    'বাহান্ন',
+    'তিপ্পান্ন',
+    'চুয়ান্ন',
+    'পঞ্চান্ন',
+    'ছাপ্পান্ন',
+    'সাতান্ন',
+    'আটান্ন',
+    'উনষাট',
+    'ষাট',
+    'একষট্টি',
+    'বাষট্টি',
+    'তেষট্টি',
+    'চৌষট্টি',
+    'পঁয়ষট্টি',
+    'ছেষট্টি',
+    'সাতষট্টি',
+    'আটষট্টি',
+    'ঊনসত্তর',
+    'সত্তর',
+    'একাত্তর',
+    'বাহাত্তর',
+    'তেহাত্তর',
+    'চুয়াত্তর',
+    'পঁচাত্তর',
+    'ছিয়াত্তর',
+    'সাতাত্তর',
+    'আটাত্তর',
+    'উনআশি',
+    'আশি',
+    'একাশি',
+    'বিরাশি',
+    'তিরাশি',
+    'চুরাশি',
+    'পঁচাশি',
+    'ছিয়াশি',
+    'সাতাশি',
+    'আটাশি',
+    'উননব্বই',
+    'নব্বই',
+    'একানব্বই',
+    'বিরানব্বই',
+    'তিরানব্বই',
+    'চুরানব্বই',
+    'পঁচানব্বই',
+    'ছিয়ানব্বই',
+    'সাতানব্বই',
+    'আটানব্বই',
+    'নিরানব্বই'
+  ]
+
+  scaleWords = [
+    '',
+    'হাজার',
+    'লাখ',
+    'কোটি',
+    'আরব',
+    'খরব',
+    'নীল',
+    'পদ্ম',
+    'শঙ্খ'
+  ]
+}
+
+export default function convertToWords (value, options = {}) {
+  return new Bengali(options).convertToWords(value)
+}

package/lib/languages/cs.js

@@ -0,0 +1,212 @@
+import SlavicLanguage from '../classes/slavic-language.js'
+
+/**
+ * @typedef {Object} SlavicOptions
+ * @property {boolean} [feminine=false] Use feminine forms for numbers.
+ */
+
+/**
+ * Czech language converter.
+ *
+ * Implements Czech number words using the Slavic language pattern:
+ * - Czech number words (jedna, dva, tři, čtyři, pět...)
+ * - Slavic three-form pluralization (tisíc/tisíce/tisíc)
+ * - Gender agreement for numbers 1-2
+ * - Czech-specific number word endings
+ *
+ * Key Features:
+ * - Three-form pluralization system shared across Slavic languages
+ *   * Form 1 (singular): 1 (e.g., "tisíc")
+ *   * Form 2 (few): 2-4, 22-24, 32-34... excluding teens (e.g., "tisíce")
+ *   * Form 3 (many): all other numbers (e.g., "tisíc")
+ * - Chunk-based decomposition (splits into groups of 3 digits: ones, thousands, millions, etc.)
+ * - Large number handling via thousands[] array with indexed [singular, few, many] forms
+ *
+ * Inherits from SlavicLanguage:
+ * - Complex pluralization rules (one/few/many forms)
+ * - Group-based large number handling (chunk decomposition via splitByX())
+ * - Proper declension patterns via pluralize() method
+ */
+export class Czech extends SlavicLanguage {
+  negativeWord = 'mínus'
+  zeroWord = 'nula'
+  ones = {
+    1: 'jedna',
+    2: 'dva',
+    3: 'tři',
+    4: 'čtyři',
+    5: 'pět',
+    6: 'šest',
+    7: 'sedm',
+    8: 'osm',
+    9: 'devět'
+  }
+
+  tens = {
+    0: 'deset',
+    1: 'jedenáct',
+    2: 'dvanáct',
+    3: 'třináct',
+    4: 'čtrnáct',
+    5: 'patnáct',
+    6: 'šestnáct',
+    7: 'sedmnáct',
+    8: 'osmnáct',
+    9: 'devatenáct'
+  }
+
+  twenties = {
+    2: 'dvacet',
+    3: 'třicet',
+    4: 'čtyřicet',
+    5: 'padesát',
+    6: 'šedesát',
+    7: 'sedmdesát',
+    8: 'osmdesát',
+    9: 'devadesát'
+  }
+
+  hundreds = {
+    1: 'sto',
+    2: 'dvě stě',
+    3: 'tři sta',
+    4: 'čtyři sta',
+    5: 'pět set',
+    6: 'šest set',
+    7: 'sedm set',
+    8: 'osm set',
+    9: 'devět set'
+  }
+
+  thousands = {
+    1: ['tisíc', 'tisíce', 'tisíc'], // 10^ 3
+    2: ['milion', 'miliony', 'milionů'], // 10^ 6
+    3: ['miliarda', 'miliardy', 'miliard'], // 10^ 9
+    4: ['bilion', 'biliony', 'bilionů'], // 10^ 12
+    5: ['biliarda', 'biliardy', 'biliard'], // 10^ 15
+    6: ['trilion', 'triliony', 'trilionů'], // 10^ 18
+    7: ['triliarda', 'triliardy', 'triliard'], // 10^ 21
+    8: ['kvadrilion', 'kvadriliony', 'kvadrilionů'], // 10^ 24
+    9: ['kvadriliarda', 'kvadriliardy', 'kvadriliard'], // 10^ 27
+    10: ['quintillion', 'quintilliony', 'quintillionů'] // 10^ 30
+  }
+
+  /**
+   * Returns the Czech word for the decimal separator based on the whole number.
+   *
+   * @returns {string} The Czech word for the decimal separator.
+   */
+  get decimalSeparatorWord () {
+    if (this.cachedWholeNumber === 0n || this.cachedWholeNumber === 1n) {
+      return 'celá'
+    } else if (this.cachedWholeNumber >= 2n && this.cachedWholeNumber <= 4n) {
+      return 'celé'
+    } else {
+      return 'celých'
+    }
+  }
+
+  /**
+   * Initializes the Czech converter with language-specific options.
+   *
+   * @param {SlavicOptions} [options={}] Configuration options (inherited from SlavicLanguage).
+   */
+  constructor (options = {}) {
+    super(options)
+
+    // Remove the inherited decimalSeparatorWord property so our getter works
+    delete this.decimalSeparatorWord
+  }
+
+  /**
+   * Implements Czech-specific three-form pluralization rules.
+   *
+   * Czech three-form system:
+   * - Form 1 (singular): exactly n=1 (e.g., "tisíc")
+   * - Form 2 (few): n ends in 2-4, excluding teens (22-24, 32-34...) (e.g., "tisíce")
+   * - Form 3 (many): all other numbers (e.g., "tisíc" for 0, 5+)
+   *
+   * @param {bigint} n The number to classify.
+   * @param {Array<string>} forms Array of [singular, few, many] word forms.
+   * @returns {string} The appropriate form for the number n.
+   */
+  pluralize (n, forms) {
+    if (n === 1n) {
+      return forms[0]
+    }
+
+    // Check if n is in the "few" form range (2-4, 22-24, 32-34, etc., excluding teens)
+    const lastDigit = n % 10n
+    const lastTwoDigits = n % 100n
+
+    if (lastDigit > 1n && lastDigit < 5n && (lastTwoDigits < 10n || lastTwoDigits > 20n)) {
+      return forms[1]
+    }
+
+    return forms[2]
+  }
+
+  /**
+   * Converts a whole number to Czech cardinal form.
+   *
+   * Algorithm (chunk-based decomposition):
+   * 1. Split number into chunks of 3 digits (right-to-left): ones, thousands, millions, etc.
+   * 2. For each non-zero chunk:
+   *    a. Extract hundreds digit (n3), tens digit (n2), ones digit (n1)
+   *    b. Add hundreds word (e.g., "sto", "dvě stě")
+   *    c. Add tens/ones (handles teens 10-19 separately from compound tens)
+   *    d. Add pluralized magnitude word (e.g., "tisíce", "miliony")
+   * 3. Join all words with spaces
+   *
+   * Example: 1234 → chunks [1, 234] → "jeden tisíc dvěstěčtyřicet"
+   *   - Chunk 1 (index=1, thousands): "jeden" + "tisíc"
+   *   - Chunk 234 (index=0): "dvě stě" + "třicet" + "čtyři"
+   *
+   * Special case: When chunk=1 at thousands+ levels, omit the ones word to avoid
+   * redundancy with the pluralized magnitude (e.g., just "tisíc" not "jeden tisíc").
+   *
+   * @param {bigint} number The whole number to convert.
+   * @returns {string} The number expressed in Czech words.
+   */
+  convertWholePart (number) {
+    if (number === 0n) {
+      return this.zeroWord
+    }
+    const words = []
+    const chunks = this.splitByX(number.toString(), 3)
+    let index = chunks.length
+    for (const x of chunks) {
+      index--
+      if (x === 0n) continue
+      const [n1, n2, n3] = this.getDigits(x)
+      if (n3 > 0n) {
+        words.push(this.hundreds[n3])
+      }
+      if (n2 > 1n) {
+        words.push(this.twenties[n2])
+      }
+      if (n2 === 1n) {
+        words.push(this.tens[n1])
+      } else if (n1 > 0n && !(index > 0 && x === 1n)) {
+        words.push(this.ones[n1])
+      }
+      if (index > 0) {
+        words.push(this.pluralize(x, this.thousands[index]))
+      }
+    }
+    return words.join(' ')
+  }
+}
+
+/**
+ * Converts a number to Czech cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {SlavicOptions} [options={}] Configuration options.
+ * @returns {string} The number expressed in Czech words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ */
+export default function convertToWords (value, options = {}) {
+  return new Czech(options).convertToWords(value)
+}