Metadata-Version: 2.1
Name: pyhannom
Version: 0.2.0
Summary: A Python toolkit for the digitization of Han-Nom characters, enabling AI and natural language processing applications with Vietnamese Han-Nom data.
Author-email: Zijie ZHANG <zijiezhang@link.cuhk.edu.hk>
License: MIT License (for code)
        
        Copyright (c) 2025 Zijie ZHANG
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        
        -------------------------------------------------------------------------------
        Data Usage Notice
        
        This project includes data derived from the "會研究吧應用漢喃 Hội Nghiên cứu và Ứng dụng Hán Nôm" project:
        
        - https://www.hannom-rcv.org/
        - https://www.hannom-rcv.org/BCHNCTD.html
        - https://www.hannom-rcv.org/Lookup-CHNC.html
        - https://www.hannom-rcv.org/converter
        
        All rights to the original data belong to the "會研究吧應用漢喃 Hội Nghiên cứu và Ứng dụng Hán Nôm".
        The data included in this package is provided strictly for research and
        educational purposes. Commercial use of the data is NOT permitted.
        
        Redistribution or modification of the data must include proper attribution
        to the original source and comply with any additional requirements set by
        the "會研究吧應用漢喃 Hội Nghiên cứu và Ứng dụng Hán Nôm".
Project-URL: Homepage, https://pypi.org/project/pyhannom/
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE

# PyHanNom

## 📖 Introduction  
**PyHanNom** is a Python package dedicated to the **modernization and digitization of Han-Nom characters**, the classical script system of Vietnam. In the era of **artificial intelligence**, where Python has become the dominant language for computation and research, it is essential to provide robust tools that connect **modern Vietnamese Latin script (Quốc Ngữ)** with its **Han-Nom heritage**.  

This package offers a foundation for computational work with Han-Nom by enabling **bidirectional lookup and conversion ↔️** at both the syllable, character, and word levels. Beyond simple character matching, PyHanNom is designed as part of a broader effort to make Han-Nom resources **machine-readable 💻, searchable 🔍, and ready for integration into AI-driven applications 🚀**.  

By bridging modern orthography with historical scripts, PyHanNom contributes to:  
- 🏛️ the **preservation and revival** of Han-Nom in digital form,  
- 📚 the **development of linguistic resources** for computational linguistics and digital humanities,  
- 🔮 and the **future of AI applications**, such as building parallel corpora between Latin Vietnamese and Han-Nom, or supporting natural language processing tasks.  

PyHanNom is therefore not only a practical tool for researchers and developers today, but also a step toward the **long-term goal of bringing Han-Nom into the digital and AI era 🌏**.

---
## PyHanNom 0.2.0
***⚠ WARNINGS ⚠***
- **The PyHanNom 0.2.0 adds new functions (load_parallel_corpus), merges the functions in 0.1.3 into fewer ones (latin_to_hannom & hannom_to_latin), and uses new data sources.**
- **The functions in 0.1.3 are still preserved but no update will be made on these functions anymore.**
- **The functions in 0.2.0 maintain at least the same functionality, and generally much better and more comprehensive.**
- **We recommend you to update to our latest 0.2.0 and use the latest functions, while the old ones can still be used.**
- **The following part will only introduce the new functions in 0.2.0.**
- **For description of functions in 0.1.3, you can refer to https://pypi.org/project/pyhannom/0.1.3/**


## 📂 Data Source
- This project includes data derived from the **"會研究吧應用漢喃 Hội Nghiên cứu và Ứng dụng Hán Nôm"** project:  
  - https://www.hannom-rcv.org/
  - https://www.hannom-rcv.org/BCHNCTD.html (used in 0.1.3 only)  
  - https://www.hannom-rcv.org/Lookup-CHNC.html
  - https://www.hannom-rcv.org/converter
- All rights to the original data belong to the *會研究吧應用漢喃 Hội Nghiên cứu và Ứng dụng Hán Nôm*.  
- The data included in this package is provided strictly for **research and educational purposes**. Commercial use of the data is **NOT permitted**.  
- Since the mappings are directly derived from this source, **all case handling and annotations in PyHanNom remain exactly consistent with the original data**. For details, please refer to the original source above.  

---

## ⚙️ Installation
```bash
pip install pyhannom
```

---

## 🚀 Usage

### 1. Load the Han-Nom table
Before using **latin_to_hannom** & **hannom_to_latin**, you need to load the Han-Nom table:

```python
from pyhannom import load_hannom_table
hannom_table = load_hannom_table()
```

This `hannom_table` handle must be passed into the following functions.

#### Function signature
```python
hannom_table()
```
- **returns**: a table to be used for **latin_to_hannom** & **hannom_to_latin**

#### Print return
You can print the return, like
```python
from pyhannom import load_hannom_table
hannom_table = load_hannom_table()
print(hannom_table[0])
print(hannom_table[1])
```
- We print `hannom_table` with `[0]` and `[1]` because it originally is a tuple with two elements (each element is a list).
- In the `[0]` element (a list), each sub-element is a `HanNomEntry` dataclass and reflects the main table entry of **工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn** (https://www.hannom-rcv.org/Lookup-CHNC.html). For example, `HanNomEntry(latin='Á', hannom='亞', examples='洲亞 Châu Á · 亞金 á kim · 亞聖 á thánh', note='U+4E9E')`.
- In the `[1]` element (a list), each sub-element is an entry from the data source of **Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm 工具轉字自𡨸國語𨖅𡨸漢喃** (https://www.hannom-rcv.org/converter/). For example, `["dát", "僁"]` or `["bính âm", "拼音"]`.

#### Use this table
You can write a loop to go through the entries of each part of the `hannom_table`, for example

***EXAMPLE 1:***
```python
from pyhannom import load_hannom_table
hannom_table = load_hannom_table()
lookup_table = hannom_table[0]
for each_lookup_entry in lookup_table:
    print(each_lookup_entry)
```
```text
HanNomEntry(latin='a', hannom='丫', examples='丫鬟 a hoàn', note='U+4E2B')
HanNomEntry(latin='A', hannom='阿', examples='阿從 a tòng · 阿諛 a dua · 阿片 a phiến · 阿羅漢 A La Hán · 阿哬！ a ha! [嘆]', note='[翻]\nU+963F')
HanNomEntry(latin='Á', hannom='亞', examples='洲亞 Châu Á · 亞金 á kim · 亞聖 á thánh', note='U+4E9E')
HanNomEntry(latin='á', hannom='啞', examples='啞𤴬 á đau', note='U+555E')
……
```

***EXAMPLE 2:***
```python
from pyhannom import load_hannom_table
hannom_table = load_hannom_table()
converter_table = hannom_table[1]
for each_converter_entry in converter_table:
    print(each_converter_entry)
```
```text
['cô ấy', '姑𧘇']
['một từ', '𠬠詞']
['“', '「']
['”', '」']
['từ mới', '詞㵋']
['từ này', '【詞尼/自尼】']
['đại từ', '代詞']
['động từ', '動詞']
……
```

---

### 2. Convert Latin → Han-Nom
Use `latin_to_hannom` to convert an Latin input into the corresponding Han-Nom.

This function has two data sources: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn (https://www.hannom-rcv.org/Lookup-CHNC.html) and 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm (https://www.hannom-rcv.org/converter/).

***EXAMPLE 1:***
```python
from pyhannom import latin_to_hannom
from pyhannom import load_hannom_table

hannom_table = load_hannom_table()
result = latin_to_hannom(hannom_table, 'ách', uncased=True, precise_match=True)
print(result)
```
```text
CHAR LEVEL: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
['厄', '阨', '呃', '軛']
CHAR LEVEL UNICODE: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
['U+5384', 'U+9628', 'U+5443', 'U+8EDB']
CHAR LEVEL ENTRY: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
[HanNomEntry(latin='ÁCH', hannom='厄', examples='災厄 tai ách', note='[翻]\nU+5384'), HanNomEntry(latin='ÁCH', hannom='阨', examples='阨塞 ách tắc', note='U+9628'), HanNomEntry(latin='ách', hannom='呃', examples='嚶呃 anh ách [聲]', note='U+5443'), HanNomEntry(latin='ÁCH', hannom='軛', examples='軛𤛠 ách trâu · 軛奴隸 ách nô lệ', note='U+8EDB')]
WORD LEVEL: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
[]
WORD LEVEL ENTRY: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
[]
HANNOM: 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm:
['厄', '阨', '呃', '軛']
LATIN: 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm:
['ách', 'ách', 'ách', 'ách']
```
***EXAMPLE 2:***
```python
from pyhannom import latin_to_hannom
from pyhannom import load_hannom_table

hannom_table = load_hannom_table()
result = latin_to_hannom(hannom_table, 'châu á', uncased=True, precise_match=True)
print(result)
```
```text
CHAR LEVEL: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
[]
CHAR LEVEL UNICODE: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
[]
CHAR LEVEL ENTRY: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
[]
WORD LEVEL: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
['洲亞', '洲亞', '鈒琫跢洲亞']
WORD LEVEL ENTRY: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
[HanNomEntry(latin='Á', hannom='亞', examples='洲亞 Châu Á · 亞金 á kim · 亞聖 á thánh', note='U+4E9E'), HanNomEntry(latin='CHÂU', hannom='洲', examples='洲亞 Châu Á · 洲陸 châu lục', note='U+6D32'), HanNomEntry(latin='cúp', hannom='鈒', examples='鈒琫跢洲亞 Cúp bóng đá châu Á [摱]', note='[翻]\nU+9212')]
HANNOM: 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm:
['洲亞']
LATIN: 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm:
['châu á']
```

#### Get the return result lists
```python
CHAR LEVEL: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
result.char_lookup   ##EXAMPLE 1: ['厄', '阨', '呃', '軛']
CHAR LEVEL UNICODE: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
result.unicode_lookup   ##EXAMPLE 1: ['U+5384', 'U+9628', 'U+5443', 'U+8EDB']
CHAR LEVEL ENTRY: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
result.char_entry_lookup   ##EXAMPLE 1: [HanNomEntry(latin='ÁCH', hannom='厄', examples='災厄 tai ách', note='[翻]\nU+5384'), HanNomEntry(latin='ÁCH', hannom='阨', examples='阨塞 ách tắc', note='U+9628'), HanNomEntry(latin='ách', hannom='呃', examples='嚶呃 anh ách [聲]', note='U+5443'), HanNomEntry(latin='ÁCH', hannom='軛', examples='軛𤛠 ách trâu · 軛奴隸 ách nô lệ', note='U+8EDB')]
WORD LEVEL: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
result.word_lookup   ##EXAMPLE 2: ['洲亞', '洲亞', '鈒琫跢洲亞']
WORD LEVEL ENTRY: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
result.word_entry_lookup   ##EXAMPLE 2: [HanNomEntry(latin='Á', hannom='亞', examples='洲亞 Châu Á · 亞金 á kim · 亞聖 á thánh', note='U+4E9E'), HanNomEntry(latin='CHÂU', hannom='洲', examples='洲亞 Châu Á · 洲陸 châu lục', note='U+6D32'), HanNomEntry(latin='cúp', hannom='鈒', examples='鈒琫跢洲亞 Cúp bóng đá châu Á [摱]', note='[翻]\nU+9212')]
HANNOM: 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm:
result.hannom_converter   ##EXAMPLE 1: ['厄', '阨', '呃', '軛']
LATIN: 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm:
result.latin_converter   ##EXAMPLE 1: ['ách', 'ách', 'ách', 'ách']
```

#### Functionality & Return content
This function merges the original 0.1.3 functions `get_chuhannom_from_latin`, `get_chuhannom_unicode_from_latin`, and `get_chuhannom_word_from_latin`.

 - For the data source 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:

   - When the input Latin is a single syllable and a single Han-Nom char should be matched, as shown in EXAMPLE 1, it will automatically return the matched Han-Nom char(s) (CHAR LEVEL), matched Han-Nom char unicode(s) (CHAR LEVEL UNICODE), and the entry(s) containing the matched Han-Nom char(s) (CHAR LEVEL ENTRY).
   - When the input Latin contains several syllables and a word or phrase should be matched, as shown in EXAMPLE 2, it will automatically return the Han-Nom word(s)/phrase(s) (WORD LEVEL) and the entry(s) containing the matched Han-Nom word(s)/phrase(s) (WORD LEVEL ENTRY).


 - For the data source 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm, it will return the Han-Nom (HANNOM) (with each corresponding Latin counterpart, LATIN) that the input Latin in or equal to the entry's Latin part (detailed matching criteria is illustrated in the `precise_match` parameter introduction below). 

#### Function signature
```python
latin_to_hannom(combined_handle, 
                latin, 
                uncased=True,
                precise_match = True)
```

- **combined_handle**: the Han-Nom table loaded by `load_hannom_table`.
- **latin**: inpurt Vietnamese in Latin script.
- **uncased** *(bool, default=True)*: whether uncased (ách) and cased (ÁCH) can be matched.
- **precise_match** *(bool, default=True)*: this only works for the matching result based on 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm.
  
  If this is `False`, the Han-Nom part in the entry will be matched as long as the input Latin is as a string in the entry's Latin part.
  If this is `True`, the Han-Nom part in the entry will be matched only when the input Latin is exactly the same as the entry's Latin part.

  For example, for the input Latin **châu á**, this being `False` will match **['洲亞', '鈒琫跢洲亞']** (['châu á', 'cúp bóng đá châu á']).
  This being `True` will only match **['洲亞']** (['châu á']).
- **returns**: The content above with 14 lines, which is discussed in detail above.

---

### 3. Convert Han-Nom → Latin
Use `hannom_to_latin` to convert an Han-Nom input into the corresponding Latin.

This function has two data sources: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn (https://www.hannom-rcv.org/Lookup-CHNC.html) and 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm (https://www.hannom-rcv.org/converter/).

***EXAMPLE 1:***
```python
from pyhannom import hannom_to_latin
from pyhannom import load_hannom_table

hannom_table = load_hannom_table()
result = hannom_to_latin(hannom_table, '心', uncased=True, precise_match=True)
print(result)
```
```text
CHAR LEVEL: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
['tâm', 'tim']
CHAR LEVEL ENTRY: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
[HanNomEntry(latin='TÂM', hannom='心', examples='決心 quyết tâm · 良心 lương tâm · 心魂 tâm hồn · 中心 trung tâm', note='U+5FC3'), HanNomEntry(latin='tim', hannom='心', examples='𬃻心 trái tim · 心肝 tim gan · 心畑 tim đèn', note='U+5FC3')]
WORD LEVEL: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
[]
WORD LEVEL ENTRY: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
[]
LATIN: 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm:
['tâm', 'tim']
HANNOM: 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm:
['心', '心']
```
***EXAMPLE 2:***
```python
from pyhannom import hannom_to_latin
from pyhannom import load_hannom_table

hannom_table = load_hannom_table()
result = hannom_to_latin(hannom_table, '洲亞', precise_match=True)
print(result)
```
```text
CHAR LEVEL: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
[]
CHAR LEVEL ENTRY: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
[]
WORD LEVEL: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
['châu á', 'châu á', 'cúp bóng đá châu á']
WORD LEVEL ENTRY: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
[HanNomEntry(latin='Á', hannom='亞', examples='洲亞 Châu Á · 亞金 á kim · 亞聖 á thánh', note='U+4E9E'), HanNomEntry(latin='CHÂU', hannom='洲', examples='洲亞 Châu Á · 洲陸 châu lục', note='U+6D32'), HanNomEntry(latin='cúp', hannom='鈒', examples='鈒琫跢洲亞 Cúp bóng đá châu Á [摱]', note='[翻]\nU+9212')]
LATIN: 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm:
['châu á']
HANNOM: 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm:
['洲亞']
```

#### Get the return result lists
```python
CHAR LEVEL: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
result.char_lookup   ##EXAMPLE 1: ['tâm', 'tim']
CHAR LEVEL ENTRY: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
result.char_entry_lookup   ##EXAMPLE 1: [HanNomEntry(latin='TÂM', hannom='心', examples='決心 quyết tâm · 良心 lương tâm · 心魂 tâm hồn · 中心 trung tâm', note='U+5FC3'), HanNomEntry(latin='tim', hannom='心', examples='𬃻心 trái tim · 心肝 tim gan · 心畑 tim đèn', note='U+5FC3')]
WORD LEVEL: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
result.word_lookup   ##EXAMPLE 2: ['châu á', 'châu á', 'cúp bóng đá châu á']
WORD LEVEL ENTRY: 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:
result.word_entry_lookup   ## EXAMPLE 2: [HanNomEntry(latin='Á', hannom='亞', examples='洲亞 Châu Á · 亞金 á kim · 亞聖 á thánh', note='U+4E9E'), HanNomEntry(latin='CHÂU', hannom='洲', examples='洲亞 Châu Á · 洲陸 châu lục', note='U+6D32'), HanNomEntry(latin='cúp', hannom='鈒', examples='鈒琫跢洲亞 Cúp bóng đá châu Á [摱]', note='[翻]\nU+9212')]
LATIN: 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm:
result.latin_converter   ## EXAMPLE 2: ['châu á']
HANNOM: 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm:
result.hannom_converter   ## EXAMPLE 2: ['洲亞']
```

#### Functionality & Return content
This function merges the original 0.1.3 functions get_latin_from_chuhannom and get_latin_word_from_chuhannom.

 - For the data source 工具查究𡨸漢喃準 Công Cụ Tra Cứu Chữ Hán Nôm Chuẩn:

   - When the input Han-Nom is a single char and a single Latin syllable should be matched, as shown in EXAMPLE 1, it will automatically return the matched Latin syllable(s) (CHAR LEVEL) and the entry(s) containing the matched Latin syllable(s) (CHAR LEVEL ENTRY).
   - When the input Han-Nom contains several chars and a Latin word or phrase should be matched, as shown in EXAMPLE 2, it will automatically return the matched Latin word(s)/phrase(s) (WORD LEVEL) and the entry(s) containing the matched Latin word(s)/phrase(s) (WORD LEVEL ENTRY).
   
 - For the data source 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm, it will return the Latin (LATIN) (with each corresponding Han-Nom counterpart, HANNOM) that the input Han-Nom in or equal to the entry's Han-Nom part (detailed matching criteria is illustrated in the `precise_match` parameter introduction below). 

#### Function signature
```python
hannom_to_latin(combined_handle, 
                hannom, 
                uncased=True,
                precise_match = True)
```

- **combined_handle**: the Han-Nom table loaded by `load_hannom_table`.
- **hannom**: inpurt Han-Nom.
- **uncased** *(bool, default=True)*: whether the Latin(s) in return (except in the entries, where Latin(s) always reflect the orginal entry case) are uncased or not.
- **precise_match** *(bool, default=True)*: this only works for the match result based on 工具轉字自𡨸國語𨖅𡨸漢喃 Công cụ chuyển tự từ chữ Quốc ngữ sang chữ Hán Nôm.
  
  If this is `False`, the Latin part in the entry will be matched as long as the input Han-Nom is as a string in the entry's Han-Nom part.
  If this is `True`, the Latin part in the entry will be matched only when the input Han-Nom is exactly the same as the entry's Han-Nom part.

  For example, for the input Han-Nom **洲亞**, this being `False` will match **['châu á', 'cúp bóng đá châu á']** (['洲亞', '鈒琫跢洲亞']).
  This being `True` will only match **['châu á']** (['洲亞']).
- **returns**: The content above with 12 lines, which is discussed in detail above.

---
### 4. Load Parallel Corpus
We build the **world-first** high-quality Vietnamese **Latin : Han-Nom** paralle corpus. **🥇🏛️📚**

We collect the sentence pairs **manually with careful inspection** from https://www.hannom-rcv.org/.

Our craftsman-like dedication to handcrafting aims to minimize noise as much as possible, as Latin : Han-Nom parallel data is very rare, and few noises and typos may effect the whole quality a lot. 

This is an invaluable resource for future Han-Nom research and revival, in both the Linguistics and Natural Language Processing perspectives.

You can use our built-in function `load_parallel_corpus` to access the whole parallel corpus.

In the parallel corpus, besides the Han-Nom and Latin sentence pairs, we also carefully annotate each pair with its source and note such as how the pair is aligned.

```python
from pyhannom import load_parallel_corpus
corpus = load_parallel_corpus()
print(corpus)
```

```
[
HanNom: 𡨸漢喃準得顯示𥪝榾𡨸漢喃準。各𡨸漢喃得𢯛攝蹺格讀。𥪝場合格讀𥞖僥、丐𱜢固𠃣數涅欣時攝𠓀。
Latin: Chữ Hán Nôm Chuẩn được hiển thị trong cột Chữ Hán Nôm Chuẩn. Các chữ Hán Nôm được sắp xếp theo cách đọc. Trong trường hợp cách đọc giống nhau, cái nào có ít số nét hơn thì xếp trước.
note: 
Source URL: https://www.hannom-rcv.org/Lookup-CHNC.html
, 
HanNom: 格𢪏𧵑各𡨸漢喃𥪝榜尼主要澦𨑗仍捲冊𢖖󠄁：『傳翹』（版𢆥1866、版𢆥1870、版𢆥1871、版𢆥1872、版𢆥1902）、『雲僊古跡新傳』、『征婦吟曲』、『春香詩集』、『嗣德聖製字學解義歌』、『大南國音字彙』、『字典𡨸喃引解』、云云。同時、衆碎㐌最優化合理𠬠數𡨸喃空常川固構築空合理。外𫥨、特別𱺵𧗱𡨸漢、各矯𡨸自『康熙字典』、即「𡨸漢正體」、拱𱺵參考關重。
Latin: Cách viết của các chữ Hán Nôm trong bảng này chủ yếu dựa trên những cuốn sách sau: Truyện Kiều (bản năm 1866, bản năm 1870, bản năm 1871, bản năm 1872, bản năm 1902), Vân Tiên Cổ Tích Tân Truyện, Chinh Phụ Ngâm Khúc, Xuân Hương thi tập, Tự Đức Thánh Chế Tự Học Giải Nghĩa Ca, Đại Nam Quấc âm tự vị, Tự Điển Chữ Nôm Dẫn Giải, vân vân. Đồng thời, chúng tôi đã tối ưu hoá hợp lí một số chữ Nôm không thường xuyên có cấu trúc không hợp lí. Ngoài ra, đặc biệt là về chữ Hán, các kiểu chữ từ Khang Hi tự điển, tức "chữ Hán chính thể", cũng là tham khảo quan trọng.
note: 在源网站上，『』里的汉喃字对应的拉丁字是斜体的，txt里无法对斜体进行区分，做机器翻译转写时可以考虑把『』洗掉
Source URL: https://www.hannom-rcv.org/Lookup-CHNC.html
, 
……
]
```

As shown above, the return is a list, with each element being a dataclass with attributes `Hannom`, `Latin`, `note`, and `Source URL`.

We will refine our note and provide English version in our future versions.

You can access one sentence pair (with its note and Source URL) using the following codes:

```python
target_pair = corpus[1]
print("THE TARGET PAIR:")
print(target_pair)
target_hannom = target_pair.hannom
print("THE HAN-NOM IN TARGET PAIR:")
print(target_hannom)
target_latin = target_pair.latin
print("THE LATIN IN TARGET PAIR:")
print(target_latin)
target_note = target_pair.note
print("THE NOTE IN TARGET PAIR:")
print(target_note)
target_source = target_pair.source_url
print("THE SOURCE URL IN TARGET PAIR:")
print(target_source)
```

```
THE TARGET PAIR:

HanNom: 格𢪏𧵑各𡨸漢喃𥪝榜尼主要澦𨑗仍捲冊𢖖󠄁：『傳翹』（版𢆥1866、版𢆥1870、版𢆥1871、版𢆥1872、版𢆥1902）、『雲僊古跡新傳』、『征婦吟曲』、『春香詩集』、『嗣德聖製字學解義歌』、『大南國音字彙』、『字典𡨸喃引解』、云云。同時、衆碎㐌最優化合理𠬠數𡨸喃空常川固構築空合理。外𫥨、特別𱺵𧗱𡨸漢、各矯𡨸自『康熙字典』、即「𡨸漢正體」、拱𱺵參考關重。
Latin: Cách viết của các chữ Hán Nôm trong bảng này chủ yếu dựa trên những cuốn sách sau: Truyện Kiều (bản năm 1866, bản năm 1870, bản năm 1871, bản năm 1872, bản năm 1902), Vân Tiên Cổ Tích Tân Truyện, Chinh Phụ Ngâm Khúc, Xuân Hương thi tập, Tự Đức Thánh Chế Tự Học Giải Nghĩa Ca, Đại Nam Quấc âm tự vị, Tự Điển Chữ Nôm Dẫn Giải, vân vân. Đồng thời, chúng tôi đã tối ưu hoá hợp lí một số chữ Nôm không thường xuyên có cấu trúc không hợp lí. Ngoài ra, đặc biệt là về chữ Hán, các kiểu chữ từ Khang Hi tự điển, tức "chữ Hán chính thể", cũng là tham khảo quan trọng.
note: 在源网站上，『』里的汉喃字对应的拉丁字是斜体的，txt里无法对斜体进行区分，做机器翻译转写时可以考虑把『』洗掉
Source URL: https://www.hannom-rcv.org/Lookup-CHNC.html

THE HAN-NOM IN TARGET PAIR:
格𢪏𧵑各𡨸漢喃𥪝榜尼主要澦𨑗仍捲冊𢖖󠄁：『傳翹』（版𢆥1866、版𢆥1870、版𢆥1871、版𢆥1872、版𢆥1902）、『雲僊古跡新傳』、『征婦吟曲』、『春香詩集』、『嗣德聖製字學解義歌』、『大南國音字彙』、『字典𡨸喃引解』、云云。同時、衆碎㐌最優化合理𠬠數𡨸喃空常川固構築空合理。外𫥨、特別𱺵𧗱𡨸漢、各矯𡨸自『康熙字典』、即「𡨸漢正體」、拱𱺵參考關重。
THE LATIN IN TARGET PAIR:
Cách viết của các chữ Hán Nôm trong bảng này chủ yếu dựa trên những cuốn sách sau: Truyện Kiều (bản năm 1866, bản năm 1870, bản năm 1871, bản năm 1872, bản năm 1902), Vân Tiên Cổ Tích Tân Truyện, Chinh Phụ Ngâm Khúc, Xuân Hương thi tập, Tự Đức Thánh Chế Tự Học Giải Nghĩa Ca, Đại Nam Quấc âm tự vị, Tự Điển Chữ Nôm Dẫn Giải, vân vân. Đồng thời, chúng tôi đã tối ưu hoá hợp lí một số chữ Nôm không thường xuyên có cấu trúc không hợp lí. Ngoài ra, đặc biệt là về chữ Hán, các kiểu chữ từ Khang Hi tự điển, tức "chữ Hán chính thể", cũng là tham khảo quan trọng.
THE NOTE IN TARGET PAIR:
在源网站上，『』里的汉喃字对应的拉丁字是斜体的，txt里无法对斜体进行区分，做机器翻译转写时可以考虑把『』洗掉
THE SOURCE URL IN TARGET PAIR:
https://www.hannom-rcv.org/Lookup-CHNC.html
```

#### Function signature
```python
load_parallel_corpus()
```

 - returns: as discussed in detail above

Making this corpus manually with care is time-consuming. We now have collected 47 pairs. We will collect more and update regularly.



---

## 📜 License
- **Code**: Licensed under the [MIT License](LICENSE).  
- **Data**: Derived from the *會研究吧應用漢喃 Hội Nghiên cứu và Ứng dụng Hán Nôm* project. Redistribution or modification of the data must include proper attribution and comply with the requirements set by the original source.  

---

## 🤝 Contributing
- Pull requests are welcome.  
- For major changes, please open an issue first to discuss what you’d like to change.  
- Make sure to update tests as appropriate.

---

## 🌏 Acknowledgments
- This project makes use of data derived from the **會研究吧應用漢喃 Hội Nghiên cứu và Ứng dụng Hán Nôm** project:  
  
  - https://www.hannom-rcv.org/
  - https://www.hannom-rcv.org/BCHNCTD.html  
  - https://www.hannom-rcv.org/Lookup-CHNC.html
  - https://www.hannom-rcv.org/converter
- All rights to the original data belong to the *會研究吧應用漢喃 Hội Nghiên cứu và Ứng dụng Hán Nôm*.  
- I would like to express my gratitude to the open-source Han-Nom community and the *會研究吧應用漢喃 Hội Nghiên cứu và Ứng dụng Hán Nôm* project for making these resources available for research and educational purposes.  
- If there is any infringement or concern regarding the use of this data, please contact me immediately. I will respond promptly to resolve the issue, including the possibility of removing this project if necessary.  

---
