n2words 1.23.0 → 1.24.0

package/lib/languages/hu.js

@@ -0,0 +1,155 @@
+import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+
+/**
+ * Hungarian language converter.
+ *
+ * Converts numbers to Hungarian words following Hungarian conventions:
+ * - Agglutinative structure for compound numbers
+ * - No spaces between tens and units (e.g., "huszonegy" = twenty-one)
+ * - Special handling for "egy" (one) - often omitted as multiplier
+ * - Vowel harmony in compound words
+ *
+ * Features:
+ * - Compact number representations (húsz, harminc, negyven)
+ * - Pre-composed twenties (huszonegy through huszonkilenc)
+ * - "egész" as decimal separator (meaning "whole")
+ * - Support for very large numbers (up to quadrilliards)
+ */
+export class Hungarian extends GreedyScaleLanguage {
+  negativeWord = 'mínusz'
+  decimalSeparatorWord = 'egész'
+  zeroWord = 'nulla'
+  scaleWordPairs = [
+    [1_000_000_000_000_000_000_000_000_000n, 'quadrilliárd'],
+    [1_000_000_000_000_000_000_000_000n, 'quadrillió'],
+    [1_000_000_000_000_000_000_000n, 'trilliárd'],
+    [1_000_000_000_000_000_000n, 'trillió'],
+    [1_000_000_000_000_000n, 'billiárd'],
+    [1_000_000_000_000n, 'billió'],
+    [1_000_000_000n, 'milliárd'],
+    [1_000_000n, 'millió'],
+    [1000n, 'ezer'],
+    [100n, 'száz'],
+    [90n, 'kilencven'],
+    [80n, 'nyolcvan'],
+    [70n, 'hetven'],
+    [60n, 'hatvan'],
+    [50n, 'ötven'],
+    [40n, 'negyven'],
+    [30n, 'harminc'],
+    [29n, 'huszonkilenc'],
+    [28n, 'huszonnyolc'],
+    [27n, 'huszonhét'],
+    [26n, 'huszonhat'],
+    [25n, 'huszonöt'],
+    [24n, 'huszonnégy'],
+    [23n, 'huszonhárom'],
+    [22n, 'huszonkettő'],
+    [21n, 'huszonegy'],
+    [20n, 'húsz'],
+    [19n, 'tizenkilenc'],
+    [18n, 'tizennyolc'],
+    [17n, 'tizenhét'],
+    [16n, 'tizenhat'],
+    [15n, 'tizenöt'],
+    [14n, 'tizennégy'],
+    [13n, 'tizenhárom'],
+    [12n, 'tizenkettő'],
+    [11n, 'tizenegy'],
+    [10n, 'tíz'],
+    [9n, 'kilenc'],
+    [8n, 'nyolc'],
+    [7n, 'hét'],
+    [6n, 'hat'],
+    [5n, 'öt'],
+    [4n, 'négy'],
+    [3n, 'három'],
+    [2n, 'kettő'],
+    [1n, 'egy'],
+    [0n, 'nulla']
+  ]
+
+  tensToCardinal (number) {
+    // Expecting `number` as bigint when called from convertWholePart
+    if (this.getScaleWord(number)) {
+      return this.getScaleWord(number)
+    } else {
+      const tens = number / 10n
+      const units = number % 10n
+      return this.getScaleWord(tens * 10n) + this.convertWholePart(units)
+    }
+  }
+
+  hundredsToCardinal (number) {
+    const hundreds = number / 100n
+    let prefix = 'száz'
+    if (hundreds !== 1n) {
+      prefix = this.convertWholePart(hundreds, '') + prefix
+    }
+    const postfix = this.convertWholePart(number % 100n, '')
+    return prefix + postfix
+  }
+
+  thousandsToCardinal (number) {
+    const thousands = number / 1000n
+    let prefix = 'ezer'
+    if (thousands !== 1n) {
+      prefix = this.convertWholePart(thousands, '') + prefix
+    }
+    const postfix = this.convertWholePart(number % 1000n, '')
+    const middle = (number <= 2000n || postfix === '') ? '' : '-'
+    return prefix + middle + postfix
+  }
+
+  bigNumberToCardinal (number) {
+    const numberLength = number.toString().length
+    const digits = (numberLength % 3 === 0) ? numberLength - 2 : numberLength
+    const exp = 10 ** (Math.floor(digits / 3) * 3)
+    const prefix = this.convertWholePart(number / BigInt(exp), '')
+    const rest = this.convertWholePart(number % BigInt(exp), '')
+    const postfix = (rest === '') ? '' : ('-' + rest)
+    return prefix + this.getScaleWord(BigInt(exp)) + postfix
+  }
+
+  convertWholePart (number, zeroWord = this.zeroWord) {
+    let words = ''
+
+    // Normalize to BigInt for consistent comparisons
+    if (typeof number !== 'bigint') number = BigInt(number)
+
+    if (number === 0n) {
+      words = zeroWord
+    } else if (zeroWord === '' && number === 2n) {
+      words = 'két'
+    } else if (number < 30n) {
+      words = this.getScaleWord(number)
+    } else if (number < 100n) {
+      words = this.tensToCardinal(number)
+    } else if (number < 1000n) {
+      words = this.hundredsToCardinal(number)
+    } else if (number < 1_000_000n) {
+      words = this.thousandsToCardinal(number)
+    } else {
+      words = this.bigNumberToCardinal(number)
+    }
+
+    return words
+  }
+}
+
+/**
+ * Converts a number to Hungarian cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options] Conversion options (see Hungarian class options).
+ * @returns {string} The number expressed in Hungarian words.
+ * @throws {TypeError} If value is NaN or invalid type.
+ * @throws {Error} If value is an invalid number string.
+ *
+ * @example
+ * convertToWords(42); // 'negyvenkettő'
+ * convertToWords(21); // 'huszonegy'
+ */
+export default function convertToWords (value, options = {}) {
+  return new Hungarian(options).convertToWords(value)
+}

package/lib/languages/id.js

@@ -0,0 +1,174 @@
+import AbstractLanguage from '../classes/abstract-language.js'
+
+/**
+ * Indonesian language converter.
+ *
+ * Converts numbers to Indonesian words following Indonesian conventions:
+ * - Simple base-10 structure
+ * - "Se-" prefix for one (e.g., "seratus" = one hundred, "seribu" = one thousand)
+ * - Space-separated number components
+ * - Straightforward grouping by thousands
+ *
+ * Key Features:
+ * - Base number mapping (base) for single digits 0-9
+ * - Magnitude scale (thousands) mapping powers of 10 to Indonesian words
+ * - Group-based algorithm:
+ *   1. Split number into groups of 3 digits
+ *   2. For each group, convert ones/tens/hundreds using base and naming rules
+ *   3. Apply "se-" prefix for 1 (seratus, seribu, sejuta)
+ *   4. Combine with magnitude words
+ *   5. Join all parts with spaces
+ * - Regular patterns (puluh for tens, ratus for hundreds, ribu for thousands)
+ * - Clear grouping: ribu (10³), juta (10⁶), miliar (10⁹), triliun (10¹²)
+ *
+ * Features:
+ * - "Se-" prefix usage for singular units
+ * - Support for very large numbers (up to decillions)
+ */
+export class Indonesian extends AbstractLanguage {
+  negativeWord = 'min'
+  decimalSeparatorWord = 'koma'
+  zeroWord = 'nol'
+  base = {
+    0: [],
+    1: ['satu'],
+    2: ['dua'],
+    3: ['tiga'],
+    4: ['empat'],
+    5: ['lima'],
+    6: ['enam'],
+    7: ['tujuh'],
+    8: ['delapan'],
+    9: ['sembilan']
+  }
+
+  thousands = {
+    3: 'ribu', // 10^3
+    6: 'juta', // 10^6
+    9: 'miliar', // 10^9
+    12: 'triliun',
+    15: 'kuadriliun',
+    18: 'kuantiliun',
+    21: 'sekstiliun',
+    24: 'septiliun',
+    27: 'oktiliun',
+    30: 'noniliun',
+    33: 'desiliun'
+  }
+
+  splitBy3 (number) {
+    // Split to groups of 3 numbers: 1234567 -> [['1'], ['234'], ['567']]
+    const blocks = []
+    const stringNumber = number.toString()
+    const length = stringNumber.length
+    let firstBlock
+
+    if (length < 3) {
+      blocks.push([stringNumber])
+    } else {
+      const firstBlockLength = length % 3
+
+      if (firstBlockLength > 0) {
+        firstBlock = [stringNumber.slice(0, firstBlockLength)]
+        blocks.push(firstBlock)
+      }
+
+      for (let index = firstBlockLength; index < length; index += 3) {
+        const nextBlock = [stringNumber.slice(index, index + 3)]
+        blocks.push(nextBlock)
+      }
+    }
+    return blocks
+  }
+
+  spell (blocks) {
+    let wordBlocks = []
+    let spelling
+    const firstBlock = blocks[0]
+    if (firstBlock[0].length === 1) {
+      spelling = firstBlock[0] === '0' ? ['nol'] : this.base[Math.trunc(firstBlock[0])]
+    } else if (firstBlock[0].length === 2) {
+      spelling = this.getTens(firstBlock[0])
+    } else {
+      spelling = [...this.getHundreds(firstBlock[0][0]), ...this.getTens(firstBlock[0].slice(1, 3))]
+    }
+    wordBlocks = [...wordBlocks, [firstBlock[0], spelling]]
+    for (let index = 1; index < blocks.length; index++) {
+      let block = blocks[index]
+      spelling = [...this.getHundreds(block[0][0]), ...this.getTens(block[0].slice(1, 3))]
+      block = [...block, spelling]
+      wordBlocks = [...wordBlocks, block]
+    }
+    return wordBlocks
+  }
+
+  getHundreds (number) {
+    if (number === '1') {
+      return ['seratus']
+    } else if (number === '0') {
+      return []
+    } else {
+      return [...this.base[Math.trunc(number)], 'ratus']
+    }
+  }
+
+  getTens (number) {
+    if (number[0] === '1') {
+      if (number[1] === '0') {
+        return ['sepuluh']
+      } else if (number[1] === '1') {
+        return ['sebelas']
+      }
+      return [...this.base[Math.trunc(number[1])], 'belas']
+    }
+
+    if (number[0] === '0') {
+      return this.base[Math.trunc(number[1])]
+    }
+
+    return [...this.base[Math.trunc(number[0])], 'puluh', ...this.base[Math.trunc(number[1])]]
+  }
+
+  join (wordBlocks) {
+    let wordList = []
+    const length = wordBlocks.length - 1
+    const firstBlock = [wordBlocks[0]]
+    let start = 0
+    if (length === 1 && firstBlock[0][0] === '1') {
+      wordList.push('seribu')
+      start = 1
+    }
+    for (let index = start; index < length + 1; index++) {
+      wordList = [...wordList, ...wordBlocks[index][1]]
+      if (wordBlocks[index][1].length === 0) {
+        continue
+      }
+      if (index === length) {
+        break
+      }
+      wordList = [...wordList, this.thousands[(length - index) * 3]]
+    }
+    return wordList.join(' ')
+  }
+
+  convertWholePart (number) {
+    return this.join(
+      this.spell(
+        this.splitBy3(number)
+      )
+    ).trim()
+  }
+}
+
+/**
+ * Converts a number to Indonesian cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options={}] Configuration options.
+ * @returns {string} The number expressed in Indonesian 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 Indonesian(options).convertToWords(value)
+}

package/lib/languages/it.js

@@ -0,0 +1,148 @@
+import GreedyScaleLanguage from '../classes/greedy-scale-language.js'
+
+/**
+ * Italian language converter.
+ *
+ * Converts numbers to Italian words following Italian conventions:
+ * - Phonetic contractions (removes duplicate vowels: "ventotto" not "ventiotto")
+ * - Accentuation rules for "tre" in compounds ("ventitré" not "ventitre")
+ * - Special handling for "uno" and vowel agreement
+ * - Complex composition patterns for large numbers
+ *
+ * Architecture Note:
+ * Unlike other GreedyScaleLanguage subclasses, Italian uses a custom algorithm
+ * rather than the standard highest-matching-scale approach. This is necessary
+ * because Italian's word formation rules are irregular and context-dependent.
+ * See tensToCardinal(), hundredsToCardinal(), and bigNumberToCardinal().
+ *
+ * Features:
+ * - Vowel elision (e.g., "ventotto" not "ventiotto")
+ * - Accentuation of final "tre" (ventitré, trentacinque - note: accent on compound tres)
+ * - Exponent-based large number naming (milione, miliardo, trilione)
+ * - Custom word construction for hundreds and thousands
+ */
+export class Italian extends GreedyScaleLanguage {
+  negativeWord = 'meno'
+  decimalSeparatorWord = 'virgola'
+  zeroWord = 'zero'
+  cardinalWords = [
+    this.zeroWord, 'uno', 'due', 'tre', 'quattro', 'cinque', 'sei', 'sette', 'otto',
+    'nove', 'dieci', 'undici', 'dodici', 'tredici', 'quattordici', 'quindici',
+    'sedici', 'diciassette', 'diciotto', 'diciannove'
+  ]
+
+  strTens = { 2: 'venti', 3: 'trenta', 4: 'quaranta', 6: 'sessanta' }
+
+  exponentPrefixes = [this.zeroWord, 'm', 'b', 'tr', 'quadr', 'quint', 'sest', 'sett', 'ott', 'nov', 'dec']
+
+  accentuate (string) {
+    const splittedString = string.split(' ')
+
+    const result = splittedString.map(word => {
+      return word.slice(-3) === 'tre' && word.length > 3 ? word.replaceAll('tré', 'tre').slice(0, -3) + 'tré' : word.replaceAll('tré', 'tre')
+    })
+    return result.join(' ')
+  }
+
+  omitIfZero (numberToString) {
+    return numberToString === this.zeroWord ? '' : numberToString
+  }
+
+  phoneticContraction (string) {
+    return string.replaceAll('oo', 'o').replaceAll('ao', 'o').replaceAll('io', 'o').replaceAll('au', 'u').replaceAll('iu', 'u')
+  }
+
+  tensToCardinal (number) {
+    const tens = Math.floor(number / 10)
+    const units = number % 10
+    const prefix = Object.prototype.hasOwnProperty.call(this.strTens, tens) ? this.strTens[tens] : this.cardinalWords[tens].slice(0, -1) + 'anta'
+    const postfix = this.omitIfZero(this.cardinalWords[units])
+    return this.phoneticContraction(prefix + postfix)
+  }
+
+  hundredsToCardinal (number) {
+    const hundreds = Math.floor(number / 100)
+    let prefix = 'cento'
+    if (hundreds !== 1) {
+      prefix = this.cardinalWords[hundreds] + prefix
+    }
+    const postfix = this.omitIfZero(this.convertWholePart(number % 100))
+    return this.phoneticContraction(prefix + postfix)
+  }
+
+  thousandsToCardinal (number) {
+    const thousands = Math.floor(number / 1000)
+    const prefix = thousands === 1 ? 'mille' : this.convertWholePart(thousands) + 'mila'
+    const postfix = this.omitIfZero(this.convertWholePart(number % 1000))
+    return prefix + postfix
+  }
+
+  exponentLengthToString (exponentLength) {
+    const prefix = this.exponentPrefixes[Math.floor(exponentLength / 6)]
+    return exponentLength % 6 === 0 ? prefix + 'ilione' : prefix + 'iliardo'
+  }
+
+  bigNumberToCardinal (number) {
+    const digits = [...number.toString()]
+
+    let preDigits = digits.length % 3
+    if (preDigits === 0) {
+      preDigits = 3
+    }
+
+    const multiplier = digits.slice(0, preDigits) // first `preDigits` elements
+    const exponent = digits.slice(preDigits) // without the first `preDigits` elements
+
+    let prefix, postfix
+    let infix = this.exponentLengthToString(exponent.length)
+
+    if (multiplier.join('') === '1') {
+      prefix = 'un '
+    } else {
+      prefix = this.convertWholePart(Math.trunc(Number(multiplier.join(''))))
+      infix = ' ' + infix.slice(0, -1) + 'i' // without last element
+    }
+
+    const isSetsEqual = (a, b) => a.size === b.size && [...a].every(value => b.has(value))
+    if (isSetsEqual(new Set(exponent), new Set(['0']))) {
+      postfix = ''
+    } else {
+      postfix = this.convertWholePart(Math.trunc(exponent.join('')))
+
+      infix += (postfix.includes(' e ') ? ', ' : ' e ')
+    }
+
+    return prefix + infix + postfix
+  }
+
+  convertWholePart (number) {
+    let words = ''
+
+    if (number < 20) {
+      words = this.cardinalWords[number]
+    } else if (number < 100) {
+      words = this.tensToCardinal(Number(number))
+    } else if (number < 1000) {
+      words = this.hundredsToCardinal(Number(number))
+    } else if (number < 1_000_000) {
+      words = this.thousandsToCardinal(Number(number))
+    } else {
+      words = this.bigNumberToCardinal(number)
+    }
+
+    return this.accentuate(words)
+  }
+}
+
+/**
+ * Converts a number to Italian cardinal (written) form.
+ *
+ * @param {number|string|bigint} value The number to convert.
+ * @param {Object} [options={}] Configuration options.
+ * @returns {string} The number expressed in Italian 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 Italian(options).convertToWords(value)
+}

package/lib/languages/ja.js

@@ -0,0 +1,190 @@
+import AbstractLanguage from '../classes/abstract-language.js'
+
+/**
+ * Japanese language converter.
+ *
+ * Converts numbers to Japanese kanji numerals using the Sino-Japanese system:
+ * - Uses kanji characters (一, 二, 三, etc.)
+ * - Grouping by 万 (man, 10,000) and 億 (oku, 100,000,000)
+ * - Unique scale units: 兆 (chō, trillion), 京 (kei, 10^16)
+ * - Special rules for 1: omitted before 十 (10), 百 (100), 千 (1000), but kept for 万 and above
+ *
+ * Key Features:
+ * - Sino-Japanese number system (standard for general counting)
+ * - Grouping by powers of 10,000 (万-based system, not 1,000)
+ * - Scale units: 万 (10^4), 億 (10^8), 兆 (10^12), 京 (10^16)
+ * - Special handling of 一 (one) prefix
+ * - Support for very large numbers up to 無量大数 (10^68)
+ *
+ * Algorithm:
+ * 1. Split number into groups of 4 digits (万-based, not 3-digit thousand-based)
+ * 2. Convert each group to kanji using special rules
+ * 3. Append appropriate scale word (万, 億, 兆, etc.)
+ * 4. Join all groups
+ *
+ * Special Rules:
+ * - 10, 100, 1000: Don't use 一 prefix (十, 百, 千 not 一十, 一百, 一千)
+ * - 10,000+: Keep 一 prefix (一万, 一億, 一兆)
+ * - Zero: 零 or 〇 (both acceptable, 零 is more formal)
+ */
+export class Japanese extends AbstractLanguage {
+  negativeWord = 'マイナス'
+  decimalSeparatorWord = '点'
+  zeroWord = '零'
+  wordSeparator = '' // Japanese doesn't use spaces between characters
+  convertDecimalsPerDigit = true // Enable digit-by-digit decimal conversion
+
+  // Digits used for group conversion (1-9)
+  digits = ['一', '二', '三', '四', '五', '六', '七', '八', '九']
+
+  // Scale words for grouping by 10^4
+  scales = [
+    '', // 10^0 (ones)
+    '万', // 10^4 (man)
+    '億', // 10^8 (oku)
+    '兆', // 10^12 (chō)
+    '京', // 10^16 (kei)
+    '垓', // 10^20 (gai)
+    '秭', // 10^24 (jo/shi)
+    '穣', // 10^28 (jō)
+    '溝', // 10^32 (kō)
+    '澗', // 10^36 (kan)
+    '正', // 10^40 (sei)
+    '載', // 10^44 (sai)
+    '極', // 10^48 (goku)
+    '恒河沙', // 10^52 (gōgasha)
+    '阿僧祇', // 10^56 (asōgi)
+    '那由他', // 10^60 (nayuta)
+    '不可思議', // 10^64 (fukashigi)
+    '無量大数' // 10^68 (muryōtaisū)
+  ]
+
+  /**
+   * Converts a group of up to 4 digits to Japanese kanji.
+   * Handles special rules for omitting 一 before 十, 百, 千.
+   *
+   * Rule: Within a group, omit 一 before 十/百/千 EXCEPT when:
+   * - It's a lower group (not isTopGroup) AND
+   * - It would be the only character in that position
+   *
+   * @param {bigint} num - Number from 0 to 9999
+   * @param {boolean} isTopGroup - Whether this is the highest non-zero group
+   * @returns {string} Japanese kanji representation
+   */
+  convertGroup (num, isTopGroup = false) {
+    if (num === 0n) return ''
+
+    const thousands = num / 1000n
+    const hundreds = (num % 1000n) / 100n
+    const tens = (num % 100n) / 10n
+    const ones = num % 10n
+
+    let result = ''
+
+    // Thousands (千)
+    if (thousands > 0n) {
+      // Always omit 一 before 千 when thousands === 1
+      if (thousands === 1n) {
+        result += '千'
+      } else {
+        result += this.digits[Number(thousands) - 1] + '千'
+      }
+    }
+
+    // Hundreds (百)
+    if (hundreds > 0n) {
+      // Always omit 一 before 百 when hundreds === 1
+      if (hundreds === 1n) {
+        result += '百'
+      } else {
+        result += this.digits[Number(hundreds) - 1] + '百'
+      }
+    }
+
+    // Tens (十)
+    if (tens > 0n) {
+      // Always omit 一 before 十 when tens === 1
+      if (tens === 1n) {
+        result += '十'
+      } else {
+        result += this.digits[Number(tens) - 1] + '十'
+      }
+    }
+
+    // Ones
+    if (ones > 0n) {
+      result += this.digits[Number(ones) - 1]
+    }
+
+    return result
+  }
+
+  /**
+   * Converts a BigInt number to Japanese cardinal form.
+   *
+   * @param {bigint} number - The number to convert
+   * @returns {string} Japanese kanji representation
+   */
+  convertWholePart (number) {
+    if (number === 0n) {
+      return this.zeroWord
+    }
+
+    let temp = number
+    let scaleIndex = 0
+    const groups = []
+
+    // Split into groups of 4 digits (万-based system)
+    while (temp > 0n) {
+      const group = temp % 10000n
+      if (group > 0n) {
+        groups.push({ value: group, scale: scaleIndex })
+      }
+      temp = temp / 10000n
+      scaleIndex++
+    }
+
+    // Reverse to process from highest to lowest
+    groups.reverse()
+
+    let result = ''
+
+    for (let i = 0; i < groups.length; i++) {
+      const { value, scale } = groups[i]
+      const isTopGroup = (i === 0)
+
+      const groupStr = this.convertGroup(value, isTopGroup)
+
+      // For scales >= 1 (万 and above), always add the scale word
+      if (scale >= 1) {
+        // Special case: if group is 1 and scale >= 1, we need 一 before the scale
+        if (value === 1n) {
+          result += '一' + this.scales[scale]
+        } else {
+          result += groupStr + this.scales[scale]
+        }
+      } else {
+        result += groupStr
+      }
+    }
+
+    return result
+  }
+}
+
+/**
+ * Converts a value to cardinal (written) form in Japanese.
+ *
+ * @param {number|string|bigint} value - Number to convert.
+ * @param {Object} [options] - Options for the converter.
+ * @returns {string} Value in Japanese kanji numerals.
+ * @throws {Error} If value is invalid.
+ *
+ * @example
+ * convertToWords(42, { lang: 'ja' }); // '四十二'
+ * convertToWords(1000, { lang: 'ja' }); // '千'
+ * convertToWords(10000, { lang: 'ja' }); // '一万'
+ */
+export default function convertToWords (value, options = {}) {
+  return new Japanese(options).convertToWords(value)
+}