n2cur

n2cur

Thư viện JavaScript / TypeScript đọc số tiền thành chữ tiếng Việt & Tiếng Anh chuẩn xác 100%
Hỗ trợ React, Angular, Vue 3, Vanilla JS / Node.js và nhúng CDN.

Website Demo Dùng Thử Trực Tuyến: https://n2cur.dts.io.vn/

Đang làm tính năng hóa đơn/thanh toán mà đau đầu vụ đọc số tiền thành chữ? Thôi đừng tự code lại nữa mấy bác! Bộ quy tắc trong n2cur đã được tối ưu qua vô số vòng nghiệm thu khó tính từ BU ngân hàng. Cài 1 dòng npm i n2cur là xong ngay!

Tính năng nổi bật

• Siêu nhẹ & Zero-Dependency: Chỉ ~12 KB không phụ thuộc bất kỳ thư viện bên thứ ba nào.
• Chính xác 100% tiếng Việt & Tiếng Anh (lang: 'en'):
  • Tiếng Việt: Đọc chuẩn các quy tắc "không trăm", "linh/lẻ", "mốt/tư/lăm", chu kỳ "tỷ tỷ" lặp lại.
  • Tiếng Anh (lang: 'en'): Đọc chuẩn theo US Short Scale (hundred, thousand, million, billion... lên tới decillion $10^{33}$), tự động số ít/số nhiều (US dollar/US dollars, cent/cents, penny/pence).
• Master Data API Linh hoạt: Nạp và tùy biến danh mục tiền tệ (VND, USD, EUR, GBP, JPY, SGD...) động từ Backend API.
• An toàn kiểu dữ liệu (Type-Safe): Hỗ trợ TypeScript type-defs đầy đủ, xử lý BigInt và số thực cực lớn mà không mất độ chính xác.
• Đa nền tảng: Hoạt động mượt mà trên React, Angular, Vue 3, Next.js, Nuxt, Node.js và trình duyệt qua CDN.

Hướng dẫn cài đặt & tích hợp từng bước

1. React (Next.js / Vite / CRA)

Bước 1: Cài đặt gói n2cur

npm install n2cur

Bước 2: Tạo Component đọc số tiền (AmountInWords.tsx)

import { useMemo } from 'react';
import { createMoneyReader, type CurrencyConfig } from 'n2cur';

export function AmountInWords({ amount, currency = 'VND', lang = 'vi', currencies }: {
  amount: string | number;
  currency?: string;
  lang?: 'vi' | 'en';
  currencies?: CurrencyConfig[];
}) {
  const reader = useMemo(() => createMoneyReader({ currencies }), [currencies]);
  const res = reader.safeRead(amount, currency, { lang });

  if (!res.ok) return <span className="error">{res.error.message}</span>;
  return <span>{res.text}</span>;
}

Bước 3: Sử dụng trong App

import { AmountInWords } from './AmountInWords';

export default function App() {
  return (
    <div>
      <p>Tiếng Việt: <AmountInWords amount="1005001" currency="VND" /></p>
      <p>English: <AmountInWords amount="105.50" currency="USD" lang="en" /></p>
    </div>
  );
}

Bước 4: Tùy chỉnh Master Data từ API (Tùy chọn)

const currencies = await fetch('/api/currencies').then(r => r.json());
<AmountInWords amount="50.5" currency="USD" currencies={currencies} />

2. Angular (Component / Standalone Pipe)

Bước 1: Cài đặt gói n2cur

npm install n2cur

Bước 2: Tạo Standalone Pipe (money-words.pipe.ts)

import { Pipe, PipeTransform } from '@angular/core';
import { safeReadMoney, type Lang } from 'n2cur';

@Pipe({
  name: 'moneyWords',
  standalone: true
})
export class MoneyWordsPipe implements PipeTransform {
  transform(amount: string | number | null | undefined, currency = 'VND', lang: Lang = 'vi'): string {
    if (amount === null || amount === undefined || amount === '') return '';
    const res = safeReadMoney(amount, currency, { lang });
    return res.ok ? res.text : '';
  }
}

Bước 3: Sử dụng trong HTML Template

<p>Thành tiền (VI): {{ totalAmount | moneyWords:'VND':'vi' }}</p>
<p>Total (EN): {{ totalAmount | moneyWords:'USD':'en' }}</p>

3. Vue 3 (Composition API)

Bước 1: Cài đặt gói n2cur

npm install n2cur

Bước 2: Tạo Component (AmountWords.vue)

<script setup lang="ts">
import { computed } from 'vue';
import { safeReadMoney, type Lang } from 'n2cur';

const props = withDefaults(defineProps<{
  amount: string | number;
  currency?: string;
  lang?: Lang;
}>(), {
  currency: 'VND',
  lang: 'vi',
});

const text = computed(() => {
  const res = safeReadMoney(props.amount, props.currency, { lang: props.lang });
  return res.ok ? res.text : res.error.message;
});
</script>

<template>
  <span>{{ text }}</span>
</template>

4. Vanilla JavaScript & TypeScript

Bước 1: Cài đặt gói n2cur

npm install n2cur

Bước 2: Đọc số tiền trực tiếp (Tiếng Việt & Tiếng Anh)

import { readMoney, safeReadMoney } from 'n2cur';

// 1. Đọc Tiếng Việt (mặc định)
console.log(readMoney(1005001, 'VND')); 
// -> "Một triệu không trăm linh năm nghìn không trăm lẻ một đồng"

console.log(readMoney('12.02', 'GBP'));  
// -> "Mười hai bảng Anh và hai pence"

// 2. Đọc Tiếng Anh (English reading support)
console.log(readMoney(105.50, 'USD', { lang: 'en' }));
// -> "One hundred five US dollars and fifty cents"

console.log(readMoney('12.01', 'GBP', { lang: 'en' }));
// -> "Twelve pounds and one penny"

// Safe read không ném Exception khi nhập dữ liệu lỗi
const res = safeReadMoney(100, 'USD', { lang: 'en' });
if (res.ok) console.log(res.text);

Bước 3: Đọc phần lẻ có dấu phẩy , kiểu Việt Nam

import { readMoney } from 'n2cur';

readMoney('1.005.001,25', 'USD', { decimalSeparator: ',' });
// -> "Một triệu không trăm linh năm đô la Mỹ và hai mươi lăm cent"

5. Nhúng trực tiếp CDN (HTML)

Bước 1: Nhúng qua CDN unpkg

<script src="https://unpkg.com/n2cur/dist/n2cur.global.js"></script>

Bước 2: Sử dụng qua biến toàn cục window.N2Cur

<script>
  // Đọc Tiếng Việt
  const viText = N2Cur.readMoney(1005001, 'VND');
  document.getElementById('total-vi').textContent = viText;

  // Đọc Tiếng Anh
  const enText = N2Cur.readMoney(105.50, 'USD', { lang: 'en' });
  document.getElementById('total-en').textContent = enText;
</script>

Cấu hình Master Data tiền tệ (API Schema)

API Reference

1. readMoney(amount, currencyCode, options?)

Đọc số tiền và trả về chuỗi kết quả. options.lang nhận 'vi' (mặc định) hoặc 'en'. Ném lỗi MoneyReaderError nếu dữ liệu hoặc tiền tệ không hợp lệ.

2. safeReadMoney(amount, currencyCode, options?)

Đọc số tiền an toàn. Trả về { ok: true, text } hoặc { ok: false, error }.

3. createMoneyReader({ currencies, lang? })

Tạo instance đọc tiền với danh mục Master Data riêng từ API và thiết lập ngôn ngữ mặc định.

License & Tác giả

Phát triển bởi dongtrieuit.

Mã nguồn mở cấp phép theo giấy phép MIT License. Repository chính thức: https://github.com/dongtrieuit/n2cur.git.