dv-normalize

A Dhivehi text normalizer for TTS frontends. Converts numbers, dates, times, fractions, scores, abbreviations, money, percentages, and other non-Thaana input into spoken-form Dhivehi.

Status: 0.1.9. The v1 rewrite ships under the existing 0.1.x line. The new public API (normalize, Normalizer, NormalizerConfig) is the supported entry point. The legacy 0.1.x classes are still exported but emit a DeprecationWarning and will be removed in a future major release.

Installation

pip install dv-normalize

Quick start

from dv_normalize import normalize

normalize("ވަކި ލާރިން ވެސް 232.23 ލާރި ހޯދައެވެ")
# 'ވަކި ލާރިން ވެސް ދުއިސައްތަ ތިރީސް ދޭއް ޕޮއިންޓް ދޭއް ތިނެއް ލާރި ހޯދައޭ'

normalize("ޑރ. އިބްރާހިމް 14:30 ގައި އައި")
normalize("ކ.އަތޮޅު ވިލިނގިލިން 120 ކިލޯ މީޓަރު")
normalize("ފޭސް2ގެ")

For repeated use, hold onto a Normalizer instance:

from dv_normalize import Normalizer, NormalizerConfig

n = Normalizer(NormalizerConfig(keep_punctuation=False))
n("ހެލޯ، ދުނިޔެ")  # → 'ހެލޯ ދުނިޔެ'

What it handles

The classifier is priority-ranked, so more specific patterns (calendar markers, multi-letter compound abbreviations, year ranges) shadow the generic ones. Tokens that don't match any rule pass through unchanged.

Configuration

NormalizerConfig(
    dialect="spoken",            # only option for now
    unknown_latin="passthrough", # "passthrough" | "drop" | "spell"
    decimal_separator="auto",    # "auto" | "dot" | "comma"
    time_system="auto",          # "auto" | "12" | "24"
    currency_default="MVR",
    keep_punctuation=True,
    diagnostic=False,
    strict=False,
)

Diagnostic mode

Normalizer.trace(text) returns the classified token list instead of joined text. Useful for debugging which rule fired:

for tok in Normalizer().trace("ޑރ. އިބްރާހިމް 2024ގައި"):
    print(tok.cls, tok.text, tok.spoken, tok.fields)

Legacy API

The original 0.1.x classes (DhivehiNumberConverter, DhivehiTimeConverter, DhivehiYearConverter, DhivehiTextProcessor) are still importable from dv_normalize but emit a DeprecationWarning. They are scheduled for removal in a future major release — migrate to normalize() / Normalizer.

License

MIT — see LICENSE.