transx 0.1.0

A lightweight, zero-dependency Python library for internationalization and translation management.

🌏 TransX

🚀 A lightweight, zero-dependency Python internationalization library that supports Python 3.7 through 3.12.

---

✨ Features

Feature	Description
🚀 Zero Dependencies	No external dependencies required
🐍 Python Support	Full support for Python 3.7-3.12
🌍 Context-based	Accurate translations with context support
📦 Standard Format	Compatible with gettext .po/.mo files
🎯 Simple API	Clean and intuitive interface
🔄 Auto Management	Automatic translation file handling
🔍 String Extraction	Built-in source code string extraction
🌐 Unicode	Complete Unicode support
🔠 Parameters	Dynamic parameter substitution
⚡ Performance	High-speed and thread-safe operations
🛡️ Error Handling	Comprehensive error management
🧪 Testing	Extensive test coverage

🚀 Quick Start

📥 Installation

pip install transx

📝 Basic Usage

from transx import TransX

# Initialize translator
tx = TransX(locales_root='locales')
tx.current_locale = 'zh_CN'

# Basic translation
print(tx.tr('Hello'))  # Output: 你好

# Translation with context
print(tx.tr('Open', context='button'))  # Output: 打开
print(tx.tr('Open', context='menu'))    # Output: 打开文件

# Translation with parameters
print(tx.tr('Hello {name}!', name='张三'))  # Output: 你好 张三！

🛠️ Command Line Interface

TransX comes with powerful CLI tools for translation management:

📤 Extract Messages

# Extract from a single file
transx extract app.py

# Extract from a directory with custom options
transx extract ./src \
    --output locales/custom.pot \
    --project "My Project" \
    --version "1.0"

🔄 Update Translations

# Update multiple languages
transx update locales/messages.pot en zh_CN ja_JP

# Custom output directory
transx update messages.pot en zh_CN --output-dir ./translations

⚙️ Compile Translations

# Compile translations
transx compile locales/*/LC_MESSAGES/messages.po

📁 Project Structure

your_project/
├── 📂 locales/
│   ├── 📂 zh_CN/
│   │   └── 📂 LC_MESSAGES/
│   │       ├── 📝 messages.po    # Source translations
│   │       └── 📦 messages.mo    # Compiled translations
│   └── 📂 ja_JP/
│       └── 📂 LC_MESSAGES/
│           ├── 📝 messages.po
│           └── 📦 messages.mo
└── 📜 your_code.py

🎯 Advanced Features

🌍 Context-Based Translations

# UI Context
print(tx.tr('Open', context='button'))  # 打开
print(tx.tr('Open', context='menu'))    # 打开文件

# Part of Speech
print(tx.tr('Post', context='verb'))    # 发布
print(tx.tr('Post', context='noun'))    # 文章

# Scene Context
print(tx.tr('Welcome', context='login')) # 欢迎登录
print(tx.tr('Welcome', context='home'))  # 欢迎回来

🛡️ Error Handling

from transx.exceptions import LocaleNotFoundError, CatalogNotFoundError

try:
    tx.current_locale = 'invalid_locale'
except LocaleNotFoundError:
    print("❌ Locale not found")

try:
    tx.load_catalog('missing_catalog.mo')
except CatalogNotFoundError:
    print("❌ Catalog not found")

📚 Multiple Catalogs

tx = TransX()
tx.load_catalog('path/to/main.mo')     # Main catalog
tx.load_catalog('path/to/extra.mo')    # Extra translations

⚡ Performance Tips

• 🚀 Uses compiled MO files for optimal speed
• 💾 Automatic translation caching
• 🔒 Thread-safe for concurrent access
• 📉 Minimal memory footprint

🤝 Contributing

Contributions are welcome! Here's how you can help:

• 🐛 Report bugs
• 💡 Suggest features
• 📝 Improve documentation
• 🔧 Submit pull requests

📄 License

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

---

Made with ❤️ by the LongHao