pylocalvoice 0.1.1

A professional Python library for local voice and Hmong language processing

PyLocalVoice 🇱🇦

A professional Python library for local voice and Hmong language processing. This library provides comprehensive tools for working with the Hmong language, including text processing, translation, grammar analysis, and educational utilities.

✨ Features

🔤 1. Phonology & Orthography

• normalize_text(): Standardize Hmong text (fix tones, case, spacing)
• syllable_split(): Split words into syllables (CV + tone structure)
• get_tone(): Detect tone markers (-b, -j, -v, -s, -g, -d, -m)
• convert_tone(): Convert syllables between different tones

📚 2. Dictionary & Translation

• translate_hm_to_en(): Translate Hmong → English (Heimbach Dict based)
• translate_en_to_hm(): Translate English → Hmong
• search_dictionary(): Search with examples and fuzzy matching

📖 3. Grammar

• detect_pos(): Detect part of speech (noun, verb, classifier, etc.)
• get_classifiers(): Get appropriate classifiers for nouns
• conjugate(): Add tense markers (past, present, future)
• substitute(): Grammar drill exercises

💬 4. Phrasebook Utilities

• get_greeting(): Get greetings (morning, afternoon, evening)
• ask_question(): Common questions (name, age, location, etc.)
• basic_dialogue(): Pre-built dialogues by topic (food, family, etc.)

🔢 5. Numbers & Measures

• num_to_hmong(): Convert numbers to Hmong words (1 = ib, 2 = ob)
• hmong_to_num(): Convert Hmong words to numbers
• convert_measure(): Unit conversions (lbs ↔ kg, miles ↔ km)

💭 6. Proverbs & Idioms

• get_proverb(): Get Hmong proverbs by topic
• explain_idiom(): Explain cultural expressions and meanings

🎓 7. Education Tools

• generate_drill(): Create pronunciation drills (tone, consonant, vowel)
• quiz_flashcards(): Flashcard sets by category (food, family, colors)
• check_pronunciation(): Analyze syllable structure and pronunciation

📦 Installation

From PyPI (Recommended)

pip install pylocalvoice

From Source

git clone https://github.com/yangnobody12/pylocalvoice.git
cd pylocalvoice
pip install -e .

For Development

git clone https://github.com/yangnobody12/pylocalvoice.git
cd pylocalvoice
pip install -e ".[dev]"

🚀 Quick Start

from pylocalvoice import pyhmong

# 1. Phonology - Normalize and analyze text
text = "kuv  YOG  neeg"
clean = pyhmong.normalize_text(text)  # "Kuv yog neeg"
tone = pyhmong.get_tone("kuv")  # "V"
converted = pyhmong.convert_tone("kuv", "b")  # "kub"

# 2. Translation - Hmong ↔ English
pyhmong.translate_hm_to_en("niam")  # "mother"
pyhmong.translate_en_to_hm("father")  # "txiv"

# 3. Grammar - Analyze and conjugate
pyhmong.detect_pos("yog")  # "verb"
pyhmong.get_classifiers("neeg")  # ["tus"]
pyhmong.conjugate("Kuv mus tsev", "past")  # "Kuv mus tsev lawm"

# 4. Phrasebook - Common phrases
pyhmong.get_greeting("morning")  # "Nyob zoo sawv ntxov"
pyhmong.ask_question("name")  # "Koj lub npe hu li cas?"

# 5. Numbers - Convert numbers
pyhmong.num_to_hmong(5)  # "tsib"
pyhmong.hmong_to_num("kaum")  # 10

# 6. Proverbs - Cultural expressions
pyhmong.get_proverb("wisdom")  # Returns Hmong proverb

# 7. Education - Learning tools
pyhmong.generate_drill("tone")  # ['pab', 'paj', 'pav', ...]
pyhmong.quiz_flashcards("food")  # {'mov': 'rice', ...}

📚 Documentation

• Features Guide - Complete guide to all 7 feature categories
• Quick Start - Get started in 5 minutes
• Installation Guide - Detailed installation instructions
• Contributing - How to contribute
• Changelog - Version history

💡 Use Cases

Language Learning

from pylocalvoice import pyhmong

# Learn basic greetings
print(pyhmong.get_greeting("morning"))  # "Nyob zoo sawv ntxov"

# Practice pronunciation with drills
drills = pyhmong.generate_drill("tone")
for drill in drills:
    print(f"Practice: {drill}")

# Quiz yourself with flashcards
cards = pyhmong.quiz_flashcards("food")

Text Processing

from pylocalvoice import pyhmong

# Clean up messy Hmong text
messy = "kuv   YOG  neeg   HMOOB"
clean = pyhmong.normalize_text(messy)  # "Kuv yog neeg hmoob"

# Analyze syllable structure
analysis = pyhmong.check_pronunciation("ntxawg")
print(analysis)  # Shows onset, nucleus, tone

Translation & Dictionary

from pylocalvoice import pyhmong

# Build a vocabulary list
words = ["niam", "txiv", "tub", "ntxhais"]
for word in words:
    english = pyhmong.translate_hm_to_en(word)
    print(f"{word} = {english}")

# Search for related words
results = pyhmong.search_dictionary("family", lang="en")

Grammar Practice

from pylocalvoice import pyhmong

# Practice tenses
sentence = "Kuv mus tsev"
print(pyhmong.conjugate(sentence, "past"))    # Add past marker
print(pyhmong.conjugate(sentence, "future"))  # Add future marker

# Learn classifiers
print(pyhmong.get_classifiers("neeg"))  # ["tus"]
print(pyhmong.get_classifiers("tsev"))  # ["lub"]

🎯 API Overview

Quick Reference

from pylocalvoice import pyhmong

# === PHONOLOGY ===
pyhmong.normalize_text(text)          # Clean text
pyhmong.get_tone(syllable)            # Get tone marker
pyhmong.convert_tone(syl, tone)       # Change tone
pyhmong.syllable_split(word)          # Split syllables

# === TRANSLATION ===
pyhmong.translate_hm_to_en(word)      # Hmong → English
pyhmong.translate_en_to_hm(word)      # English → Hmong
pyhmong.search_dictionary(query)      # Search both ways

# === GRAMMAR ===
pyhmong.detect_pos(word)              # Part of speech
pyhmong.get_classifiers(noun)         # Get classifiers
pyhmong.conjugate(sent, tense)        # Add tense
pyhmong.substitute(sent, old, new)    # Replace words

# === PHRASEBOOK ===
pyhmong.get_greeting(time)            # Greetings
pyhmong.ask_question(topic)           # Questions
pyhmong.basic_dialogue(unit)          # Dialogues

# === NUMBERS ===
pyhmong.num_to_hmong(n)               # 5 → "tsib"
pyhmong.hmong_to_num(word)            # "ib" → 1
pyhmong.convert_measure(val, f, t)    # Unit conversion

# === PROVERBS ===
pyhmong.get_proverb(topic)            # Get proverb
pyhmong.explain_idiom(phrase)         # Explain idiom

# === EDUCATION ===
pyhmong.generate_drill(type)          # Pronunciation drills
pyhmong.quiz_flashcards(category)     # Flashcards
pyhmong.check_pronunciation(word)     # Check structure

🔧 Advanced Usage

Batch Processing

from pylocalvoice import pyhmong

# Process multiple texts
texts = [
    "Kuv yog neeg Hmoob",
    "Koj nyob li cas?",
    "Peb mus tsev"
]

for text in texts:
    clean = pyhmong.normalize_text(text)

    print(f"Text: {text}")
    print(f"Clean: {clean}")

    # Translate each word
    for word in clean.split():
        translation = pyhmong.translate_hm_to_en(word)
        print(f"  {word} = {translation}")
    print()

📊 Statistics

• 22 main functions across 7 categories
• 100+ Hmong words in dictionary
• 8 tone markers supported
• 40+ consonants (including digraphs and trigraphs)
• 15+ vowels (simple and complex)
• 3 dialogue units with 12+ phrases
• 3 flashcard categories (food, family, colors)

🗺️ Roadmap

Version 0.2.0 (Planned)

• Extended dictionary (1000+ words)
• Pahawh Hmong script support
• Audio pronunciation guide
• More dialogue units (10+ topics)

Version 0.3.0 (Future)

• White Hmong vs Green Hmong dialect support
• Text-to-speech integration
• Advanced grammar parser
• Named entity recognition

Version 1.0.0 (Long-term)

• Machine translation
• Language detection
• Part-of-speech tagger (full)
• Web API wrapper
• Mobile app support

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Ways to contribute:

• Add more words to dictionary
• Create new dialogue units
• Add proverbs and idioms
• Improve pronunciation drills
• Write documentation
• Report bugs
• Suggest features

📖 Resources

Learn More About Hmong Language

• Hmong Language Wikipedia
• RPA Romanization System
• Heimbach Hmong Dictionary

Related Projects

• Hmong Dictionary Online
• White Hmong Resources

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Thanks to the Hmong community for preserving this beautiful language
• Based on Ernest E. Heimbach's White Hmong-English Dictionary
• Inspired by various NLP libraries and linguistic research
• Built with modern Python best practices

📧 Contact & Support

• Author: YangNobody12
• Email: [e-mail]
• PyPI: https://pypi.org/project/pylocalvoice/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

⭐ Show Your Support

If you find this library helpful, please consider:

• Starring the repository ⭐
• Sharing with others who learn Hmong
• Contributing to the project
• Reporting issues and suggesting features

📝 Citation

If you use this library in your research or project, please cite:

@software{pylocalvoice,
  author = {YangNobody12},
  title = {PyLocalVoice: A Comprehensive Python Library for Hmong Language Processing},
  year = {2025},
  url = {https://github.com/yangnobody12/pylocalvoice},
  version = {0.1.0}
}

---

Made with ❤️ for the Hmong community

Ua tsaug! (Thank you!)