italian-numbers

Converts numbers to Italian word representations and vice versa. Supports cardinal numbers, ordinal numbers, and Roman numerals.

Includes TypeScript declarations and ESM, CommonJS, and browser bundles, with no runtime dependencies.

Quick start · API reference · Development

Installation

npm install italian-numbers
# or: yarn add italian-numbers

The library targets ES2021, including String.replaceAll and regular expression lookbehind, and requires no DOM APIs. ESM/CommonJS examples have been checked on Node.js 20.10.0, 22.23.2, and 24.15.0; no minimum Node.js or browser version is guaranteed by these checks. Development requirements are listed below.

Quick start

import {
  toItalianCardinal,
  toItalianOrdinal,
  parseItalianNumber,
  toRoman,
  parseRoman,
} from 'italian-numbers';

// Cardinal numbers
toItalianCardinal(1); // 'uno'
toItalianCardinal(21); // 'ventuno'
toItalianCardinal(709); // 'settecentonove'

// Negative numbers
toItalianCardinal(-34); // 'meno trentaquattro'

// Decimals: two digits, without rounding
toItalianCardinal(1000.05, { includeDecimals: true }); // 'mille/05'
toItalianCardinal(9, { includeDecimals: true }); // 'nove/00'
toItalianCardinal(1.999, { includeDecimals: true }); // 'uno/99'

// Ordinal numbers
toItalianOrdinal(1); // 'primo'
toItalianOrdinal(10); // 'decimo'
toItalianOrdinal(3.9); // 'terzo'

// Ordinals: feminine
toItalianOrdinal(1, { female: true }); // 'prima'
toItalianOrdinal(15, { female: true }); // 'quindicesima'

// Ordinals: plural
toItalianOrdinal(1, { plural: true }); // 'primi'
toItalianOrdinal(18, { plural: true }); // 'diciottesimi'

// Ordinals: feminine plural
toItalianOrdinal(1, { female: true, plural: true }); // 'prime'
toItalianOrdinal(70, { female: true, plural: true }); // 'settantesime'

// Italian words to numbers
parseItalianNumber('uno'); // 1
parseItalianNumber('novantasette'); // 97
parseItalianNumber('un milione tredicimila'); // 1013000
parseItalianNumber('meno trentaquattro'); // -34
parseItalianNumber('meno dieci/45'); // -10.45

// Ordinal words to numbers
parseItalianNumber('zeresimo'); // 0
parseItalianNumber('prima'); // 1
parseItalianNumber('quattrocentotredicesime'); // 413
parseItalianNumber('infinitesimi'); // Infinity

// Numbers to Roman numerals
toRoman(1); // 'I'
toRoman(49); // 'XLIX'
toRoman(2317); // 'MMCCCXVII'

// Roman numerals to numbers
parseRoman('MD'); // 1500
parseRoman('XLIX'); // 49
parseRoman('MCMXC'); // 1990

// Unrecognized Italian text
Number.isNaN(parseItalianNumber('primavera')); // true

CommonJS

const { toItalianCardinal } = require('italian-numbers');
toItalianCardinal(21); // 'ventuno'

Browser

Load the IIFE bundle before calling functions on window.italianNumbers:

<script src="https://unpkg.com/italian-numbers@^1/dist/index.global.js"></script>
<script>
  console.log(window.italianNumbers.toItalianCardinal(21)); // 'ventuno'
</script>

Try all five functions in the interactive demo.

API Reference

| Function | Input | Output | Invalid input | |----------|-------|--------|---------------| | toItalianCardinal | number, options? | Cardinal string | Throws Error | | toItalianOrdinal | number, options? | Ordinal string | Throws Error | | parseItalianNumber | Italian string | number | Returns NaN | | toRoman | number | Roman numeral string | Throws Error | | parseRoman | Roman numeral string | number | Throws Error |

Use the documented input types. Check parsing failures with Number.isNaN(result) for parseItalianNumber, and use try/catch for functions that throw. Additional examples are included in the functions' JSDoc.

toItalianCardinal(number, options?)

• Range: -999999999999 to 999999999999, plus Infinity / -Infinity ("infinito" / "meno infinito").
• Options: CardinalConverterOptions has includeDecimals?: boolean (default false).
• The integer part is truncated toward zero. With includeDecimals: true, append /XX using two decimal digits without rounding: 1.999 → "uno/99", 9 → "nove/00".
• Errors: "not a number" for NaN; "greater than 999999999999" or "lower than -999999999999" for out-of-range values.

toItalianOrdinal(number, options?)

• Range: 0 to 999999999999, plus Infinity ("infinitesimo").
• Options: OrdinalConverterOptions has female?: boolean and plural?: boolean, both defaulting to false. Combine them for feminine plural: 1 → "prime".
• Nonnegative decimals are truncated: toItalianOrdinal(3.9) → "terzo". Gender and plural options also apply to Infinity.
• Errors: "not a number" for NaN, "negative number not allowed" for negative values, and "greater than 999999999999" above the supported range.

parseItalianNumber(word)

Accepts cardinals, ordinals in all forms, negatives, and infinity words such as "infinito" or "infinitesimi". Normalizes case, Unicode accents, whitespace, and the conjunction e.

Decimals require exactly two digits after /: "zero/50" → 0.5, "meno dieci/45" → -10.45. Malformed words or number groups, numeric strings such as "21", and spoken decimals such as "dieci virgola quarantacinque" return NaN.

toRoman(number)

Accepts integers from 1 to 3999, plus Infinity → "infinitum". Fractions are rejected. Errors: "not a number" for NaN, "not an integer" for non-integers, "lower than 1" or "greater than 3999" for out-of-range integers.

parseRoman(roman)

Accepts standard uppercase Roman numerals, returning an integer from 1 to 3999, or the exact string "infinitum", returning Infinity. Invalid strings, including empty strings and lowercase numerals such as "xlix", throw Error('invalid roman number').

Development

Use Node.js 24.15.0 (.nvmrc) and Yarn 1.22.22 (packageManager) for development. The toolchain uses TypeScript 6, tsdown, Jest 30, and ESLint 10.

nvm use
corepack enable
yarn install --frozen-lockfile
yarn lint
yarn typecheck
yarn test:coverage
yarn build
yarn test:package

yarn watch runs the TypeScript entry point; a clean exit is expected because it only exports functions. yarn build:watch rebuilds the distributable files.

CI and releases require 100% statements, branches, functions, and lines across src/**/*.ts, plus lint, type checks, build, and package verification for CJS, ESM, IIFE, and TypeScript consumers. The HTML report is coverage/index.html; demo handlers have separate regression tests outside the library coverage metric.

Files in src/functions/ match the new function names and contain their deprecated aliases. src/index.ts only re-exports the API. See AGENTS.md for project conventions; Codex also has $review and $commit-msg skills in .agents/skills/.

Contributing

Fork the repository, create a feature branch, run the development checks above, and open a pull request. Use conventional commits such as feat:, fix:, or docs: for semantic-release.

License

MIT - Nicolo Zandarin