adyghe-latin-utils 0.1.1

Python utilities for Adyghe (Western Circassian) language: Cyrillic↔Latin alphabet conversion and number-to-words conversion

adyghe-latin-utils

🌐 English | Türkçe | Русский | עברית

Python utilities for the Adyghe (Western Circassian) language — Cyrillic↔Latin alphabet conversion and number-to-words conversion.

About Adyghe

Adyghe (адыгабзэ / adıǵabze) is a Northwest Caucasian language spoken by approximately 600,000 people, primarily in the Republic of Adygea (Russia), Turkey, Jordan, Syria, and diaspora communities worldwide. Its ISO 639-3 language code is ady.

Adyghe is traditionally written in the Cyrillic script (since 1938). A Latin-based Adyghe alphabet also exists as an official writing system. This package provides tools for converting between these two official alphabets, as well as converting numbers into Adyghe words.

Features

• Cyrillic → Latin conversion — context-aware conversion between the official Cyrillic and Latin Adyghe alphabets, handling compound characters (гу, гъ, дж, дз, жь, кӀ, ку, шъ, etc.)
• Latin → Cyrillic conversion — reverse conversion with vowel insertion and palochka (Ӏ) rules
• Number to words — converts integers (0 to 10¹⁵) into Adyghe words using the modern decimal (base-10) system
• Numbers in text — detects and converts 12 types of numeric patterns in mixed text: phone numbers, currencies ($), percentages (%), ranges (7-12), decimals (5.11), Roman numerals (IV), signed numbers (+14, -32), and more
• Case utilities — uppercase, lowercase, and capitalize with proper handling of special Latin characters (İ/ı) and Cyrillic palochka (Ӏ)
• Script detection — detect whether text is written in Cyrillic Adyghe
• CLI tools — command-line utilities for batch file conversion with multiprocessing support

Installation

pip install adyghe-latin-utils

Or with uv:

uv add adyghe-latin-utils

Quick Start

Alphabet Conversion

from adyghe_latin_utils import AdigaCharacterUtils

utils = AdigaCharacterUtils()

# Cyrillic to Latin
utils.cyrillic_to_latin("гупшысэ")        # → "ǵupşıśé"
utils.cyrillic_to_latin("лъэхъаным")      # → "ĺéḣáním"
utils.cyrillic_to_latin("къещхы")          # → "kéşḣı"

# Latin to Cyrillic
utils.latin_to_cyrillic("selam")           # → "сэлам"
utils.latin_to_cyrillic("adıǵe")          # → "адыгэ"

# Script detection
utils.is_cyrillic_adyghe("гупшысэ")       # → True
utils.is_cyrillic_adyghe("ǵupşıśé")      # → False

Number to Words

This library uses the modern decimal (base-10) system for number-to-words conversion. Adyghe traditionally uses a vigesimal (base-20) counting system similar to French (e.g., French soixante-douze = 60 + 12 for "72"). In the traditional Adyghe system, "72" is ṫoćişıre ṫure (roughly "three-twenties-and-twelve"). Modern usage has shifted towards a simpler decimal (base-10) system:

Number	Modern decimal (this library)	Traditional vigesimal (not supported)
72	blıć ṫu (7-tens and 2)	ṫoćişıre ṫure (3×20 + 12)

from adyghe_latin_utils import AdigaNumberUtils

AdigaNumberUtils.number_to_words(5)        # → "tfı"
AdigaNumberUtils.number_to_words(42)       # → "pĺ'ıć ṫu"
AdigaNumberUtils.number_to_words(100)      # → "şe"
AdigaNumberUtils.number_to_words(1000)     # → "min"
AdigaNumberUtils.number_to_words(2025)     # → "ṫu min ṫuć tfı"

Numbers in Mixed Text

from adyghe_latin_utils import AdigaNumberUtils

AdigaNumberUtils.convert_numbers_in_text("chapter 3")
# → "chapter şı"

AdigaNumberUtils.convert_numbers_in_text("agent 007")
# → "agent ziy ziy blı"

AdigaNumberUtils.convert_numbers_in_text("the year 2025")
# → "the year ṫu min ṫuć tfı"

Case Utilities

from adyghe_latin_utils import AdigaCharacterUtils

utils = AdigaCharacterUtils()

# Latin text
utils.to_lowercase("ADIGE", is_latin=True, is_cyrillic=False)
utils.to_uppercase("adıǵe", is_latin=True, is_cyrillic=False)
utils.capitalize("adıǵe", is_latin=True, is_cyrillic=False)

# Simplify special Latin chars to basic English
utils.special_chars_to_english_chars("ǵupşıśé")  # → "gupsise"

CLI Usage

Two command-line tools are installed with the package:

Script Conversion

# Cyrillic to Latin (file to file)
adyghe-char-convert -i input.txt -o output.txt -d c2l

# Latin to Cyrillic (file to stdout)
adyghe-char-convert -i input.txt -d l2c

# Options:
#   -i, --input      Path to input text file (required)
#   -o, --output     Path to output file (default: stdout)
#   -d, --direction  c2l (Cyrillic→Latin) or l2c (Latin→Cyrillic) (required)

The script conversion CLI supports multiprocessing for large files and displays a progress bar.

Number Conversion

# Convert numbers in a text string
adyghe-num-convert -t "chapter 3"

# Convert numbers in a file
adyghe-num-convert -i input.txt -o output.txt

# Options:
#   -t, --text    Input text string (mutually exclusive with -i)
#   -i, --input   Path to input text file (mutually exclusive with -t)
#   -o, --output  Path to output file (default: stdout)

API Reference

AdigaCharacterUtils

Method	Description
cyrillic_to_latin(text: str) -> str	Convert Cyrillic Adyghe text to Latin script
latin_to_cyrillic(text: str) -> str	Convert Latin Adyghe text to Cyrillic script
is_cyrillic_adyghe(text: str, threshold: float = 0.5) -> bool	Detect if text is Cyrillic Adyghe
to_lowercase(text, is_latin, is_cyrillic) -> str	Lowercase with script-aware rules
to_uppercase(text, is_latin, is_cyrillic) -> str	Uppercase with script-aware rules
capitalize(text, is_latin, is_cyrillic) -> str	Capitalize first character
special_chars_to_english_chars(text: str) -> str	Simplify accented Latin chars to ASCII
cyrillic_extra_chars_to_basic_chars(text: str) -> str	Normalize Cyrillic character variants

AdigaNumberUtils

Method	Description
number_to_words(number: int) -> str	Convert integer (0–10¹⁵) to Adyghe words
convert_numbers_in_text(text: str) -> str	Find and convert all numeric patterns in text

Supported Numeric Patterns

convert_numbers_in_text() recognizes and converts these patterns:

Pattern	Example	Description
International phone	[phone]	Digits read individually
Local phone	058-206-2315	Digits read individually
Prefix-dash	ya-20	Number converted, prefix preserved
Postfix-dash	13-re	Number converted, postfix preserved
Dollar amount	$16,918	Full number conversion
Signed number	+14, -32	Sign preserved, number converted
Range	1042-1814	Each number converted separately
Decimal	5.11, 50.06%	Integer and fractional parts converted
Slash-separated	2010/11	Each part converted
Symbol postfix	4%, 804+	Number converted, symbol preserved
Roman numeral	III, IV	Converted to Arabic then to words
Plain number	42, 1,000,000	Full number conversion

Development

# Clone the repository
git clone https://github.com/showgan/adyghe-latin-utils.git
cd adyghe-latin-utils

# Set up development environment
uv venv
uv pip install -e ".[dev]"

# Run tests
uv run pytest tests/ -v

License

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