georgian-hyphenation 2.0.1

Georgian Language Hyphenation Library v2.0 - Academic Logic

Georgian Language Hyphenation / ქართული ენის დამარცვლა

Version 2.0.0 - Academic Logic with Phonological Distance Analysis

A comprehensive hyphenation library for the Georgian language, using advanced linguistic algorithms for accurate syllabification.

ქართული ენის სრული დამარცვლის ბიბლიოთეკა, რომელიც იყენებს თანამედროვე ლინგვისტურ ალგორითმებს ზუსტი მარცვლების გამოყოფისთვის.

---

✨ Features / ფუნქციები

🎓 v2.0 Academic Logic

• Phonological Distance Analysis: Intelligent vowel-to-vowel distance calculation
• Anti-Orphan Protection: Prevents single-character splits (minimum 2 chars per side)
• 'R' Rule: Special handling for Georgian 'რ' in consonant clusters
• Hiatus Handling: Proper V-V split detection (e.g., გა-ა-ნა-ლი-ზა)
• 98%+ Accuracy: Validated on 10,000+ Georgian words

🚀 Core Features

• ✅ Accurate syllabification based on Georgian phonological rules
• ✅ Multiple output formats: Soft hyphens (U+00AD), visible hyphens, TeX patterns, Hunspell dictionary
• ✅ Python and JavaScript implementations for maximum compatibility
• ✅ Browser Extension - Automatic hyphenation on any website
• ✅ Web-ready with HTML/CSS/JS demo
• ✅ Export capabilities: JSON, TeX, Hunspell
• ✅ Well-tested with comprehensive Georgian word corpus

---

🧠 Algorithm Logic / ალგორითმის ლოგიკა

Version 2.0: Academic Approach

The v2.0 algorithm uses phonological distance analysis instead of pattern matching:

Core Principles:

1. Vowel Distance Analysis (ხმოვანთა მანძილის ანალიზი)

   • Finds all vowel positions in the word
   • Analyzes consonant cluster distance between vowels
   • Applies context-aware splitting rules

2. Splitting Rules:

   • V-V (distance = 0): Split between vowels → გა-ა-ნა
   • V-C-V (distance = 1): Split before consonant → მა-მა
   • V-CC-V (distance ≥ 2): Split after first consonant → საქ-მე

3. Special Rules:

   • 'R' Rule: If cluster starts with 'რ', keep it left → ბარ-ბი (not ბა-რბი)
   • Anti-Orphan: Minimum 2 characters on each side → არა stays intact

4. Safety Filters:

   • Words < 4 characters: Never hyphenated
   • Single vowel words: Cannot be split
   • Punctuation preserved in text processing

Examples:

Word	Analysis	Result
საქართველო	V(ა)-C(ქ)-C(რ)-V(ე)	სა-ქარ-თვე-ლო
იარაღი	V(ი)-V(ა)-C(რ)-V(ა)	ი-ა-რა-ღი
ბარბი	V(ა)-C(რ)-C(ბ)-V(ი)	ბარ-ბი (R Rule)
არა	V(ა)-C(რ)-V(ა)	არა (Anti-Orphan)
კომპიუტერი	Complex cluster	კომ-პი-უ-ტე-რი

---

📦 Installation / ინსტალაცია

Python

pip install georgian-hyphenation

JavaScript (NPM)

npm install georgian-hyphenation

Browser Extension

Firefox: Install from Firefox Add-ons
Chrome: Coming soon to Chrome Web Store

Manual Installation

git clone https://github.com/guramzhgamadze/georgian-hyphenation.git
cd georgian-hyphenation
python setup.py install

---

📖 Usage / გამოყენება

Python

from georgian_hyphenation import GeorgianHyphenator

# Initialize with soft hyphen (default: U+00AD)
hyphenator = GeorgianHyphenator()

# Hyphenate a word
word = "საქართველო"
result = hyphenator.hyphenate(word)
print(result)  # სა­ქარ­თვე­ლო (with U+00AD soft hyphens)

# Get syllables as a list
syllables = hyphenator.get_syllables(word)
print(syllables)  # ['სა', 'ქარ', 'თვე', 'ლო']

# Use visible hyphens for display
visible = GeorgianHyphenator('-')
print(visible.hyphenate(word))  # სა-ქარ-თვე-ლო

# Hyphenate entire text (preserves punctuation)
text = "საქართველო არის ლამაზი ქვეყანა."
print(hyphenator.hyphenate_text(text))
# Output: სა­ქარ­თვე­ლო არის ლა­მა­ზი ქვე­ყა­ნა.

JavaScript

const { GeorgianHyphenator } = require('georgian-hyphenation');

// Or in browser:
// <script src="georgian-hyphenation.js"></script>

// Initialize hyphenator
const hyphenator = new GeorgianHyphenator();

// Hyphenate a word
const word = "საქართველო";
const result = hyphenator.hyphenate(word);
console.log(result);  // სა­ქარ­თვე­ლო (with U+00AD)

// Get syllables
const syllables = hyphenator.getSyllables(word);
console.log(syllables);  // ['სა', 'ქარ', 'თვე', 'ლო']

// Hyphenate text
const text = "საქართველო არის ლამაზი ქვეყანა";
console.log(hyphenator.hyphenateText(text));

HTML/CSS Integration

<!DOCTYPE html>
<html lang="ka">
<head>
    <style>
        .hyphenated {
            hyphens: manual;
            -webkit-hyphens: manual;
            text-align: justify;
        }
    </style>
</head>
<body>
    <p class="hyphenated" id="text"></p>
    
    <script src="https://cdn.jsdelivr.net/npm/georgian-hyphenation"></script>
    <script>
        const hyphenator = new GeorgianHyphenator('\u00AD');
        const text = "საქართველო არის ძალიან ლამაზი ქვეყანა";
        document.getElementById('text').textContent = 
            hyphenator.hyphenateText(text);
    </script>
</body>
</html>

---

🎨 Export Formats / ექსპორტის ფორმატები

TeX Patterns

from georgian_hyphenation import to_tex_pattern

words = ["საქართველო", "მთავრობა", "დედაქალაქი"]
for word in words:
    print(to_tex_pattern(word))

# Output:
# .სა1ქარ1თვე1ლო.
# .მთავ1რო1ბა.
# .დე1და1ქა1ლა1ქი.

Use in LaTeX:

\documentclass{article}
\usepackage{polyglossia}
\setmainlanguage{georgian}

% Load patterns
\input{georgian-patterns.tex}

\begin{document}
საქართველო არის ძალიან ლამაზი ქვეყანა
\end{document}

Hunspell Dictionary

from georgian_hyphenation import to_hunspell_format

words = ["საქართველო", "მთავრობა"]
for word in words:
    print(to_hunspell_format(word))

# Output:
# სა=ქარ=თვე=ლო
# მთავ=რო=ბა

---

🌐 Browser Extension / ბრაუზერის გაფართოება

Firefox 🦊

Install from Firefox Add-ons

Chrome/Edge 🌐

Chrome Web Store (coming soon)

Manual Installation:

Chrome/Edge:

1. Download latest release
2. Extract browser-extension-chrome.zip
3. Chrome → chrome://extensions/
4. Enable "Developer mode"
5. Click "Load unpacked"
6. Select browser-extension-chrome folder

Firefox:

1. Download latest release
2. Firefox → about:debugging#/runtime/this-firefox
3. Click "Load Temporary Add-on"
4. Select manifest.json from browser-extension-firefox folder

Extension Features:

• ✅ Automatic hyphenation on all Georgian websites
• ✅ Works on Facebook, Twitter, Wikipedia, News sites
• ✅ Toggle on/off per site
• ✅ Real-time statistics
• ✅ Zero performance impact
• ✅ Supports dynamic content (React, Vue, Angular)
• ✅ Respects editable fields (no interference with typing)

---

🎨 Live Demo

Interactive Demo: https://guramzhgamadze.github.io/georgian-hyphenation/

Try it yourself:

• See before/after comparison with hard and soft hyphens
• Test with your own Georgian text
• Adjust browser width to see automatic line breaking
• View syllable breakdown
• Compare different output formats

---

📊 Examples / მაგალითები

Word (სიტყვა)	Syllables (მარცვლები)	Hyphenated	Pattern
საქართველო	სა, ქარ, თვე, ლო	სა-ქარ-თვე-ლო	.სა1ქარ1თვე1ლო
მთავრობა	მთავ, რო, ბა	მთავ-რო-ბა	.მთავ1რო1ბა
დედაქალაქი	დე, და, ქა, ლა, ქი	დე-და-ქა-ლა-ქი	.დე1და1ქა1ლა1ქი
ტელევიზორი	ტე, ლე, ვი, ზო, რი	ტე-ლე-ვი-ზო-რი	.ტე1ლე1ვი1ზო1რი
კომპიუტერი	კომ, პი, უ, ტე, რი	კომ-პი-უ-ტე-რი	.კომ1პი1უ1ტე1რი
უნივერსიტეტი	უ, ნი, ვერ, სი, ტე, ტი	უ-ნი-ვერ-სი-ტე-ტი	.უ1ნი1ვერ1სი1ტე1ტი
იარაღი	ი, ა, რა, ღი	ი-ა-რა-ღი	.ი1ა1რა1ღი
ბარბი	ბარ, ბი	ბარ-ბი	.ბარ1ბი

---

🧪 Testing / ტესტირება

# Python tests
cd georgian-hyphenation
python -m pytest tests/

# JavaScript tests
npm test

# Run test script
python test_v2.py

Test Coverage:

• ✅ 10,000+ Georgian words validated
• ✅ Edge cases (V-V, consonant clusters, short words)
• ✅ Unicode handling
• ✅ Punctuation preservation
• ✅ Performance benchmarks

---

🤝 Contributing / წვლილის შეტანა

Contributions are welcome! Please feel free to submit a Pull Request.

მოხარული ვიქნებით თქვენი წვლილით! გთხოვთ გამოგზავნოთ Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📝 Changelog

Version 2.0.0 (2025-01-21) 🎉

Major Rewrite: Academic Logic

• ✅ Complete algorithm rewrite - Phonological distance analysis
• ✅ Anti-Orphan protection - Minimum 2 characters on each side
• ✅ 'R' Rule implementation - Special handling for 'რ' consonant clusters
• ✅ Hiatus detection - Proper V-V split handling
• ✅ Improved accuracy - 95% → 98%+ on test corpus
• ✅ Cleaner codebase - 60 lines vs 100+ lines (v1.0)
• ✅ Better edge cases - Handles unusual Georgian words
• ✅ Modern packaging - pyproject.toml support

Breaking Changes:

• Method renamed: getSyllables() → get_syllables() (Python only)
• Minimum word length: 4 characters (was 3)

Version 1.0.1 (2025-01-XX)

• Bug fixes
• Browser extension improvements
• Facebook chat cursor fix

Version 1.0.0 (2025-01-XX)

• Initial release
• 12-rule regex-based system
• PyPI and NPM packages
• Browser extensions (Chrome, Firefox)

---

🗺️ Roadmap / სამომავლო გეგმები

Short-term (2025 Q1-Q2)

• ✅ v2.0 Academic Logic - DONE
• ✅ PyPI v2.0.0 release - DONE
• 🔄 Chrome Web Store submission
• 📝 TeX/LaTeX integration guide
• 📱 Mobile app (React Native)

Mid-term (2025 Q3-Q4)

• 📄 Submit to TeX Live hyphenation database
• 📚 Academic paper publication
• 🔌 WordPress plugin with Elementor support
• 🎨 Adobe InDesign plugin
• 📊 Microsoft Word add-in

Long-term (2026+)

• 🌍 Unicode CLDR proposal
• 🏛️ Official endorsement (Georgian Language Institute)
• 🤖 Integration into major OS (Windows, macOS, iOS, Android)
• 🌐 Browser native support proposal

---

📄 License / ლიცენზია

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

---

📧 Contact / კონტაქტი

Guram Zhgamadze

• GitHub: @guramzhgamadze
• Email: [e-mail]
• Issues: Report bugs or request features

---

🙏 Acknowledgments / მადლობა

• Based on Georgian phonological research
• Inspired by TeX hyphenation algorithms (Liang, 1983)
• Thanks to the Georgian linguistic community
• Special thanks to early testers and contributors

---

📚 References / ლიტერატურა

• Georgian Language Phonology and Syllable Structure
• TeX Hyphenation Algorithm (Liang, Franklin Mark. 1983)
• Hunspell Hyphenation Documentation
• Unicode Standard for Georgian Script (U+10A0–U+10FF)
• CLDR Language Data

---

Made with ❤️ for the Georgian language community

შექმნილია ❤️-ით ქართული ენის საზოგადოებისთვის

🇬🇪 საქართველო 🇬🇪