{"id":17053655,"url":"https://github.com/edditoria/numbo","last_synced_at":"2025-04-12T16:46:17.674Z","repository":{"id":58241326,"uuid":"74664750","full_name":"Edditoria/numbo","owner":"Edditoria","description":"A Javascript library to convert number and monetary amount to written text in multiple languages. Also helpful for writing cheques (checks). Supports English, and 支援中文.","archived":false,"fork":false,"pushed_at":"2020-11-15T08:51:39.000Z","size":652,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-14T13:06:25.242Z","etag":null,"topics":["bower","hacktoberfest","javascript-library","npm-package","number-to-words"],"latest_commit_sha":null,"homepage":"https://edditoria.github.io/numbo/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Edditoria.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-11-24T10:56:43.000Z","updated_at":"2022-10-02T15:13:12.000Z","dependencies_parsed_at":"2022-08-31T00:40:49.782Z","dependency_job_id":null,"html_url":"https://github.com/Edditoria/numbo","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edditoria%2Fnumbo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edditoria%2Fnumbo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edditoria%2Fnumbo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edditoria%2Fnumbo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Edditoria","download_url":"https://codeload.github.com/Edditoria/numbo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239952606,"owners_count":19723922,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bower","hacktoberfest","javascript-library","npm-package","number-to-words"],"created_at":"2024-10-14T10:12:52.526Z","updated_at":"2025-02-21T19:30:33.235Z","avatar_url":"https://github.com/Edditoria.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Numbo: Convert Number to Native Languages\n\nNumbo is a Javascript library to convert number and monetary amount to written text in multiple languages. Also helpful for writing cheques (checks). Currently, it supports English, Simplified Chinese and Traditional Chinese. Available in npm and bower.\n\n\\(Numbo 是一個 Javascript 程式庫，將阿拉伯數字轉換成繁體中文丶簡體中文及英文，另有提供支票用的大寫格式 :\\)\n\nQuick examples:\n\n```js\nvar numbo = new Numbo();\n\n// converting a number, monetary amount or check(cheque) writing\nnumbo.convert('3.14'); // 'three point one four'\nnumbo.convert('0.5', { type: 'amount' }); // 'fifty cents'\nnumbo.convert('100', { type: 'check' }); // 'One Hundred Dollars and No Cent Only'\n\n// Simplified Chinese\nnumbo.convert('3.14', { lang: 'zhCN', type: 'number' }); // '三点一四'\nnumbo.convert('0.5', { lang: 'zhCN', type: 'amount' }); // '五角'\nnumbo.convert('100', { lang: 'zhCN', type: 'check' }); // '壹佰元整'\n\n// Traditional Chinese\nnumbo.convert('3.14', { lang: 'zhTW', type: 'number' }); // '三點一四'\nnumbo.convert('0.5', { lang: 'zhTW', type: 'amount' }); // '五角'\nnumbo.convert('100', { lang: 'zhTW', type: 'check' }); // '壹佰元正'\n```\n\n\n## Install and Usage\n\nNumbo can be installed via npm or Bower, or run in browser directly.\n\n**Important:** This README is based on v3.0.0-rc.0. For `numbo@latest`, please see [Numbo v2.5](https://github.com/Edditoria/numbo/tree/v2.5.0)\n\n### npm\n\n```shell\nnpm install numbo@next\n```\n\nFor node.js\n\n```js\nimport Numbo from 'numbo'; // points to numbo/esm/index.mjs in node 14\n// import Numbo from 'numbo/esm/index.mjs'; // same as above\n// var Numbo = require('numbo/bundles/numbo.min.js'); // node \u003c=12\nvar numbo = new Numbo();\nconsole.log(numbo.convert('123.45')); // one hundred and twenty-three point four five\n```\n\n### Bower\n\nYou can download and easily update `numbo` via [Bower package manager](https://bower.io/).\n\n```shell\nbower install numbo\n```\n\nAnd it is ready to serve in front-end environment:\n\n```html\n\u003chtml\u003e\n\t\u003chead\u003e\n\t\t\u003cscript src='bower_components/numbo/bundles/numbo.min.js'\u003e\u003c/script\u003e\n\t\u003c/head\u003e\n\u003c/html\u003e\n\n```\n\n```js\nvar numbo = new Numbo();\nconsole.log(numbo.convert('123.45')); // one hundred and twenty-three point four five\n```\n\n### Direct Download\n\nNothing can stop you. Download the file `numbo.min.js` and refer it in your html file:\n\n```html\n\u003chtml\u003e\n\t\u003chead\u003e\n\t\t\u003cscript src='numbo.min.js'\u003e\u003c/script\u003e\n\t\u003c/head\u003e\n\u003c/html\u003e\n```\n\nAnd you are ready to go:\n\n```js\nvar numbo = new Numbo();\nconsole.log(numbo.convert('123.45')); // one hundred and twenty-three point four five\n```\n\n\n## Features Highlight\n\n### Basic Usage: `numbo.convert(input, options)`\n\n`input` is the string (recommended) or number you want to convert.\n`options` is a Javascript object for format of output you want to get:\n\n1. `options.lang`: Either 'enUS' (default), 'zhTW' or 'zhCN'.\n1. `options.type`: Either 'number' (default), 'amount' or 'check'.\n1. `options.zeroCent`: `true` to get check amount \"with Zero Cent\" instead of \"with No Cent\". Default is `false`.\n\n```js\nvar options = {};\nvar input = '12.3456';\n\nnumbo.convert(input, options);\n// no option implies { lang: 'enUS', type: 'number' }\n// return 'twelve point three four five six'\n\noptions.type = 'amount';\nnumbo.convert(input, options);\n// 'amount' will round up (ceiling) to 2 decimal place\n// return 'twelve dollars and thirty-five cents'\n\noptions.type = 'check';\nnumbo.convert('100', options);\n// 'check' will round up (ceiling) to 2 decimal place\n// return 'One Hundred Dollars and No Cent Only'\n\noptions.zeroCent = true;\nnumbo.convert('100', options);\n// return 'One Hundred Dollars and Zero Cent Only'\n```\n\n### Define Numbo Instances\n\nIn v3.x, you can create a Numbo instance with constructor options using `new Numbo(options)`.\n\n```js\nvar input = '100';\nvar optionsEnChk = { lang: 'enUS', type: 'check', zeroCent: true };\nvar numboEnChk = new Numbo(optionsEnChk);\n\nnumboEnChk.convert(input, { type: 'amount' });\n// .convert() still accepts options (as one-time options)\n// return 'one hundred dollars'\n\nnumboEnChk.convert(input);\n// then convert using instance options this time\n// return 'One Hundred Dollars and Zero Cent Only'\n\nnumboEnChk.convert(input, { lang: 'zhTW' });\n// .convert() to 'check' according to optionsEnChk\n// return '壹佰元正'\n\n// Define as many as you want\nvar numboTwChk = new Numbo({ lang: 'zhTW', type: 'check' });\nvar numboCnChk = new Numbo({ lang: 'zhCN', type: 'check' });\nvar numboCnAmt = new Numbo({ lang: 'zhCN', type: 'amount' });\n```\n\nMore format will be provided in future releases, e.g. no hyphen, no \"and\" word, return error, etc. For any request, please [hit me an issue](https://github.com/Edditoria/numbo/issues).\n\n### Format of `input`\n\n- Accepts string (recommended) and number, e.g. '30624700'.\n- You must use a string if the input is more than 16 characters.\n- Limitations:\n\t- English module supports up to 66 digits, i.e. hundred vigintillion.\n\t- Simplified and Traditional Chinese modules support up to 48 digits, i.e. 千載.\n\n### Alias `options.type`\n\nYou can write in short form:\n\n- `'num'` is equivalent to `'number'`\n- `'amt'` is equivalent to `'amount'`\n- `'chk'`, `'chq'` and `'cheque'` are equivalent to `'check'`\n\n```js\nnumbo.convert('100', { type: 'amt', lang: 'zhTW' });\n```\n\n### Play with Numbo-Options\n\nThe Numbo-options is designed to bring anywhere in Numbo.\n\n```js\nvar numbo = new Numbo({ lang: 'zhTW' });\n\n// Get current options\nnumbo.getOptions(); // { lang: 'zhTW', type: 'number' }\n\n// Add or override option(s)\nnumbo.setOptions({ type: 'cheque' }); // { lang: 'zhTW', type: 'cheque' }\n\n// See the default Numbo options\nnumbo.getDefaultOptions(); // { lang: 'enUS', type: 'number' }\n\n// Reset to Numbo default\nnumbo.resetOptions(); // { lang: 'enUS', type: 'number' }\n```\n\n### Import Modules\n\nThanks to stable Conditional Exports in Node 14, you can import ESM modules via Node or build tools. With npm install, you can simply:\n\n- `import Numbo from 'numbo'` to get Numbo object in `esm/index.mjs`.\n- `import enUS from 'numbo/en-us'` to get enUS function in `esm/en-us.mjs`.\n- `import normalize from 'numbo/utils/normalize'` to get the normalize utility module.\n- And etc.\n\nAlthough I recommend you develop using Node 14+, suppose this package still works for Node \u003c 14, Webpack, Rollup and other build tools using the \"exports\", \"main\" and \"module\" configs in `\u003cpackage.json\u003e`.\n\nThis Numbo feature is **in development stage**. I need your comments and suggestions. Welcome Issues.\n\n### Parsing and Catching Errors (Work-In-Progress)\n\nNumbo will try to do some checking and normalize the input. Let say:\n\n```js\ncutFromNews = '$1,000,000.00';\nrobot.speak += numbo.convert(cutFromNews, { type: 'amt' });\n// 'one million dollars'\n\ncutFromEmail = '.5';\nrobot.speak += numbo.convert(cutFromEmail);\n// 'zero point five'\n\nreadScore = '0050.50';\nrobot.speak += numbo.convert(readScore);\n// 'fifty point five'\n```\n\nCurrently Numbo is quite stupid. Anything it cannot convert. Will `console.log` a message then return `null`.\n\n```js\nnumbo.convert('knock knock'); // Error: Invalid input value. Return null\nnumbo.convert('HKD777'); // Error: Invalid input value. Return null\n```\n\n\n## Copyright and License\n\nCopyright (c) 2016-2020 Edditoria. All rights reserved. Code released under the [MIT License](LICENSE.txt). Docs released under [Creative Commons](https://creativecommons.org/licenses/by/4.0/).\n\nAs human-readable summary (but not a substitute for the license):\n\nYou can use it, share it, modify the code and distribute your work for private and commercial uses. If you like, please share your work with me. :pizza:\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedditoria%2Fnumbo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedditoria%2Fnumbo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedditoria%2Fnumbo/lists"}