# nghimestudio/vietnormalizer architecture

> Architecture diagram of the GitHub repository nghimestudio/vietnormalizer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nghimestudio/vietnormalizer
- Repository: https://github.com/nghimestudio/vietnormalizer

## Overview

vietnormalizer is a Python library for converting Vietnamese text into normalized, speech-friendly text. Its main workflow is a caller passing text to VietnameseNormalizer, which delegates number/date/time and text processing to VietnameseTextProcessor, then applies dictionary replacements and optionally transliterates remaining non-Vietnamese words. Detection and transliteration are also available as direct library functions. README features fill in several conversion stages; sampled excerpts do not establish their individual internal call paths.

Main entry points: [`vietnormalizer/processor.py`](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py) (Text processor), [`vietnormalizer/normalizer.py`](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/normalizer.py) (Text normalizer), [`vietnormalizer/__init__.py`](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/__init__.py) (Package exports), [`vietnormalizer/transliterator.py`](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/transliterator.py) (Rule transliterator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_exports["Package exports<br/>[__init__.py]"]
end

subgraph group_normalize["Normalization Pipeline"]
  node_normalizer["Text normalizer<br/>[normalizer.py]"]
  node_processor["Text processor<br/>[processor.py]"]
  node_dicts["Dictionary lookup<br/>[normalizer.py]"]
  node_cleaning["Unicode and cleanup<br/>[processor.py]"]
  node_numbers["Number conversion<br/>[processor.py]"]
  node_dates["Date and time conversion<br/>[processor.py]"]
  node_currency["Currency and percent<br/>[processor.py]"]
  node_units["Measurement conversion<br/>[processor.py]"]
  node_phone["Phone conversion<br/>[processor.py]"]
  node_ordinal["Ordinal conversion<br/>[processor.py]"]
end

subgraph group_language["Language Resources"]
  node_detector["Vietnamese detector<br/>[detector.py]"]
  node_transliterator["Rule transliterator<br/>[transliterator.py]"]
  node_acronym_data["Acronym dictionary<br/>[acronyms.csv]"]
  node_word_data["Word dictionary"]
end

node_caller(("Library caller"))

node_caller -->|"imports"| node_exports
node_exports -->|"exports"| node_normalizer
node_exports -->|"exports"| node_processor
node_exports -->|"exports"| node_detector
node_exports -->|"exports"| node_transliterator
node_caller -->|"normalizes text"| node_normalizer
node_normalizer -->|"processes text"| node_processor
node_normalizer -->|"applies replacements"| node_dicts
node_normalizer -->|"transliterates leftovers"| node_transliterator
node_normalizer -->|"checks words"| node_detector
node_dicts -->|"loads"| node_acronym_data
node_dicts -->|"loads"| node_word_data
node_processor -->|"cleans text"| node_cleaning
node_processor -->|"converts numbers"| node_numbers
node_processor -->|"converts dates"| node_dates
node_processor -->|"converts amounts"| node_currency
node_processor -->|"converts units"| node_units
node_processor -->|"reads digits"| node_phone
node_processor -->|"converts ordinals"| node_ordinal
node_transliterator -->|"checks Vietnamese"| node_detector

click node_exports "https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/__init__.py"
click node_normalizer "https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/normalizer.py"
click node_processor "https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py"
click node_dicts "https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/normalizer.py"
click node_detector "https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/detector.py"
click node_transliterator "https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/transliterator.py"
click node_acronym_data "https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/data/acronyms.csv"
click node_word_data "https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/data/non-vietnamese-words.csv"
click node_cleaning "https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py"
click node_numbers "https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py"
click node_dates "https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py"
click node_currency "https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py"
click node_units "https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py"
click node_phone "https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py"
click node_ordinal "https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_exports toneBlue
class node_normalizer,node_processor,node_dicts,node_cleaning,node_numbers,node_dates,node_currency,node_units,node_phone,node_ordinal toneAmber
class node_detector,node_transliterator,node_acronym_data,node_word_data toneMint
class node_caller toneIndigo
```

## Components

### Public API

- [Package exports](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/__init__.py): `vietnormalizer/__init__.py`

### Normalization Pipeline

- [Text normalizer](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/normalizer.py): `vietnormalizer/normalizer.py`
- [Text processor](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py): `vietnormalizer/processor.py`
- [Dictionary lookup](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/normalizer.py): `vietnormalizer/normalizer.py`
- [Unicode and cleanup](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py): `vietnormalizer/processor.py`
- [Number conversion](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py): `vietnormalizer/processor.py`
- [Date and time conversion](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py): `vietnormalizer/processor.py`
- [Currency and percent](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py): `vietnormalizer/processor.py`
- [Measurement conversion](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py): `vietnormalizer/processor.py`
- [Phone conversion](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py): `vietnormalizer/processor.py`
- [Ordinal conversion](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/processor.py): `vietnormalizer/processor.py`

### Language Resources

- [Vietnamese detector](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/detector.py): `vietnormalizer/detector.py`
- [Rule transliterator](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/transliterator.py): `vietnormalizer/transliterator.py`
- [Acronym dictionary](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/data/acronyms.csv): `vietnormalizer/data/acronyms.csv`
- [Word dictionary](https://github.com/nghimestudio/vietnormalizer/blob/main/vietnormalizer/data/non-vietnamese-words.csv): `vietnormalizer/data/non-vietnamese-words.csv`

### Other components

- **Library caller**

## Connections

- Library caller → Package exports: imports
- Package exports → Text normalizer: exports
- Package exports → Text processor: exports
- Package exports → Vietnamese detector: exports
- Package exports → Rule transliterator: exports
- Library caller → Text normalizer: normalizes text
- Text normalizer → Text processor: processes text
- Text normalizer → Dictionary lookup: applies replacements
- Text normalizer → Rule transliterator: transliterates leftovers
- Text normalizer → Vietnamese detector: checks words
- Dictionary lookup → Acronym dictionary: loads
- Dictionary lookup → Word dictionary: loads
- Text processor → Unicode and cleanup: cleans text
- Text processor → Number conversion: converts numbers
- Text processor → Date and time conversion: converts dates
- Text processor → Currency and percent: converts amounts
- Text processor → Measurement conversion: converts units
- Text processor → Phone conversion: reads digits
- Text processor → Ordinal conversion: converts ordinals
- Rule transliterator → Vietnamese detector: checks Vietnamese