| Name | transx JSON |
| Version |
0.2.2
JSON |
| download |
| home_page | None |
| Summary | A lightweight, zero-dependency Python library for internationalization and translation management. |
| upload_time | 2024-12-04 17:04:28 |
| maintainer | None |
| docs_url | None |
| author | longhao |
| requires_python | <4.0,>=2.7 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# π TransX
π A lightweight, zero-dependency Python internationalization library that supports Python 2.7 through 3.12.
The API is designed to be [DCC](https://en.wikipedia.org/wiki/Digital_content_creation)-friendly, for example, works with [Maya](https://www.autodesk.com/products/maya/overview), [3DsMax](https://www.autodesk.com/products/3ds-max/overview), [Houdini](https://www.sidefx.com/products/houdini/), etc.
<div align="center">
[](https://img.shields.io/pypi/pyversions/transx)
[](https://github.com/wntrblm/nox)
[](https://pypi.org/project/transx/)
[](https://pepy.tech/project/transx)
[](https://pepy.tech/project/transx)
[](https://pepy.tech/project/transx)
[](https://pypi.org/project/transx/)
[](https://pypi.org/project/transx/)
[](https://github.com/loonghao/transx/graphs/commit-activity)
</div>
---
## β¨ Features
TransX provides a comprehensive set of features for internationalization:
- π **Zero Dependencies**: No external dependencies required
- π **Python Support**: Full support for Python 2.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**: Named, positional and ${var} style parameters
- π« **Variable Support**: Environment variable expansion support
- β‘ **Performance**: High-speed and thread-safe operations
- π‘οΈ **Error Handling**: Comprehensive error management with fallbacks
- π§ͺ **Testing**: 100% test coverage with extensive cases
- π **Auto Translation**: Built-in Google Translate API support
- π₯ **DCC Support**: Tested with Maya, 3DsMax, Houdini, etc.
- π **Extensible**: Pluggable custom text interpreters system
- π¨ **Flexible Formatting**: Support for various string format styles
- π **Runtime Switching**: Dynamic locale switching at runtime
## π Language Code Support
TransX provides flexible language code handling with automatic normalization. The library supports multiple formats for language codes, making it easy to use in different contexts.
#### Supported Language Codes
| Language | Standard Code | Alternative Formats |
|----------|--------------|-------------------|
| Chinese (Simplified) | `zh_CN` | `zh-CN`, `zh_Hans`, `Chinese`, `Chinese Simplified` |
| Japanese | `ja_JP` | `ja`, `Japanese` |
| Korean | `ko_KR` | `ko`, `Korean` |
| English | `en_US` | `en`, `English` |
| French | `fr_FR` | `fr`, `French` |
| Spanish | `es_ES` | `es`, `Spanish` |
| German | `de_DE` | `de`, `German` |
| Italian | `it_IT` | `it`, `Italian` |
| Russian | `ru_RU` | `ru`, `Russian` |
For a complete list of supported languages, refer to the [language code documentation](https://cloud.google.com/translate/docs/languages).
```python
from transx import TransX
tx = TransX()
# All these formats are valid:
tx.current_locale = "zh-CN" # Hyphen format
tx.current_locale = "zh_CN" # Underscore format
tx.current_locale = "zh" # Language only
tx.current_locale = "Chinese" # Language name
```
## π Quick Start
### π₯ Installation
```bash
pip install transx
```
### π Basic Usage
```python
from transx import TransX
# Initialize with locale directory
tx = TransX(locales_root="./locales")
# Basic translation
print(tx.tr("Hello")) # Output: δ½ ε₯½
# Translation with parameters
print(tx.tr("Hello {name}!", name="εΌ δΈ")) # Output: δ½ ε₯½ εΌ δΈοΌ
# Context-based translation
print(tx.tr("Open", context="button")) # ζεΌ
print(tx.tr("Open", context="menu")) # ζεΌζδ»Ά
# Switch language at runtime
tx.current_locale = "ja_JP"
print(tx.tr("Hello")) # Output: γγγ«γ‘γ―
```
### π Advanced Parameter Substitution
```python
# Named parameters
tx.tr("Welcome to {city}, {country}!", city="εδΊ¬", country="δΈε½")
# Positional parameters
tx.tr("File {0} of {1}", 1, 10)
# Dollar sign variables (useful in shell-like contexts)
tx.tr("Current user: ${USER}") # Supports ${var} syntax
tx.tr("Path: $HOME/documents") # Supports $var syntax
# Escaping dollar signs
tx.tr("Price: $$99.99") # Outputs: Price: $99.99
```
## π οΈ Command Line Interface
TransX provides a powerful CLI for translation management:
### Extract Messages
```bash
# Extract from a single file
transx extract app.py -o messages.pot
# Extract from a directory
transx extract ./src -o messages.pot -p "MyProject" -v "1.0"
```
### Update PO Files
```bash
# Update or create PO files for specific languages
transx update messages.pot -l zh_CN ja_JP ko_KR
# Auto-translate during update
transx update messages.pot -l zh_CN ja_JP ko_KR --translate
```
### Compile MO Files
```bash
# Compile a single PO file
transx compile locales/zh_CN/LC_MESSAGES/messages.po
# Compile all PO files in a directory
transx compile locales
```
## π― Advanced Features
### Context-Based Translations
```python
# 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
TransX provides comprehensive error handling with fallback mechanisms:
```python
from transx import TransX
from transx.exceptions import LocaleNotFoundError, TranslationError
# Enable strict mode for development
tx = TransX(strict_mode=True)
try:
tx.load_catalog("invalid_locale")
except LocaleNotFoundError as e:
print(f"β Locale error: {e.message}")
try:
result = tx.translate("Hello", target_lang="invalid")
except TranslationError as e:
print(f"β Translation failed: {e.message}")
```
## π€ Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
### π Project Structure
```
transx/
βββ transx/ # Main package directory
β βββ api/ # Public API modules
β β βββ locale.py # Locale handling
β β βββ mo.py # MO file operations
β β βββ po.py # PO file operations
β β βββ translate.py # Translation services
β βββ core.py # Core functionality
β βββ cli.py # Command-line interface
β βββ constants.py # Constants and configurations
β βββ exceptions.py # Custom exceptions
βββ tests/ # Test directory
βββ examples/ # Example code and usage
βββ nox_actions/ # Nox automation scripts
βββ docs/ # Documentation
βββ pyproject.toml # Project configuration
βββ noxfile.py # Test automation configuration
```
## β‘ Performance Features
- π Uses compiled MO files for optimal speed
- πΎ Automatic translation caching
- π Thread-safe for concurrent access
- π Minimal memory footprint
- π Automatic PO to MO compilation
### π§ Development Setup
1. Clone the repository:
```bash
git clone https://github.com/loonghao/transx.git
cd transx
```
2. Install development dependencies:
```bash
pip install -r requirements-dev.txt
```
### π Development Workflow
We use [Nox](https://nox.thea.codes/) to automate development tasks. Here are the main commands:
```bash
# Run linting
nox -s lint
# Fix linting issues automatically
nox -s lint-fix
# Run tests
nox -s pytest
```
### π§ͺ Running Tests
Tests are written using pytest and can be run using nox:
```bash
nox -s pytest
```
For running specific tests:
```bash
# Run a specific test file
nox -s pytest -- tests/test_core.py
# Run tests with specific markers
nox -s pytest -- -m "not integration"
```
### π Code Quality
We maintain high code quality standards using various tools:
- **Linting**: We use ruff and isort for code linting and formatting
- **Type Checking**: Static type checking with mypy
- **Testing**: Comprehensive test suite with pytest
- **Coverage**: Code coverage tracking with coverage.py
- **CI/CD**: Automated testing and deployment with GitHub Actions
### π Documentation
Documentation is written in Markdown and is available in:
- README.md: Main documentation
- examples/: Example code and usage
- API documentation in source code
### π€ Contributing Guidelines
1. Fork the repository
2. Create a new branch for your feature
3. Make your changes
4. Run tests and linting
5. Submit a pull request
Please ensure your PR:
- Passes all tests
- Includes appropriate documentation
- Follows our code style
- Includes test coverage for new features
## π License
This project is licensed under the MIT License - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "transx",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=2.7",
"maintainer_email": null,
"keywords": null,
"author": "longhao",
"author_email": "hal.long@outlook.com",
"download_url": "https://files.pythonhosted.org/packages/c0/b5/47024db837e2b81798ada11d2ee50e1704aba1ed7ea08d53ab99f8b7d901/transx-0.2.2.tar.gz",
"platform": null,
"description": "# \ud83c\udf0f TransX\n\n\ud83d\ude80 A lightweight, zero-dependency Python internationalization library that supports Python 2.7 through 3.12.\n\nThe API is designed to be [DCC](https://en.wikipedia.org/wiki/Digital_content_creation)-friendly, for example, works with [Maya](https://www.autodesk.com/products/maya/overview), [3DsMax](https://www.autodesk.com/products/3ds-max/overview), [Houdini](https://www.sidefx.com/products/houdini/), etc.\n\n\n<div align=\"center\">\n\n[](https://img.shields.io/pypi/pyversions/transx)\n[](https://github.com/wntrblm/nox)\n[](https://pypi.org/project/transx/)\n[](https://pepy.tech/project/transx)\n[](https://pepy.tech/project/transx)\n[](https://pepy.tech/project/transx)\n[](https://pypi.org/project/transx/)\n[](https://pypi.org/project/transx/)\n[](https://github.com/loonghao/transx/graphs/commit-activity)\n\n</div>\n\n---\n\n## \u2728 Features\n\nTransX provides a comprehensive set of features for internationalization:\n\n- \ud83d\ude80 **Zero Dependencies**: No external dependencies required\n- \ud83d\udc0d **Python Support**: Full support for Python 2.7-3.12\n- \ud83c\udf0d **Context-based**: Accurate translations with context support\n- \ud83d\udce6 **Standard Format**: Compatible with gettext .po/.mo files\n- \ud83c\udfaf **Simple API**: Clean and intuitive interface\n- \ud83d\udd04 **Auto Management**: Automatic translation file handling\n- \ud83d\udd0d **String Extraction**: Built-in source code string extraction\n- \ud83c\udf10 **Unicode**: Complete Unicode support\n- \ud83d\udd20 **Parameters**: Named, positional and ${var} style parameters\n- \ud83d\udcab **Variable Support**: Environment variable expansion support\n- \u26a1 **Performance**: High-speed and thread-safe operations\n- \ud83d\udee1\ufe0f **Error Handling**: Comprehensive error management with fallbacks\n- \ud83e\uddea **Testing**: 100% test coverage with extensive cases\n- \ud83c\udf10 **Auto Translation**: Built-in Google Translate API support\n- \ud83c\udfa5 **DCC Support**: Tested with Maya, 3DsMax, Houdini, etc.\n- \ud83d\udd0c **Extensible**: Pluggable custom text interpreters system\n- \ud83c\udfa8 **Flexible Formatting**: Support for various string format styles\n- \ud83d\udd04 **Runtime Switching**: Dynamic locale switching at runtime\n\n## \ud83c\udf0d Language Code Support\n\nTransX provides flexible language code handling with automatic normalization. The library supports multiple formats for language codes, making it easy to use in different contexts.\n\n#### Supported Language Codes\n\n| Language | Standard Code | Alternative Formats |\n|----------|--------------|-------------------|\n| Chinese (Simplified) | `zh_CN` | `zh-CN`, `zh_Hans`, `Chinese`, `Chinese Simplified` |\n| Japanese | `ja_JP` | `ja`, `Japanese` |\n| Korean | `ko_KR` | `ko`, `Korean` |\n| English | `en_US` | `en`, `English` |\n| French | `fr_FR` | `fr`, `French` |\n| Spanish | `es_ES` | `es`, `Spanish` |\n| German | `de_DE` | `de`, `German` |\n| Italian | `it_IT` | `it`, `Italian` |\n| Russian | `ru_RU` | `ru`, `Russian` |\n\nFor a complete list of supported languages, refer to the [language code documentation](https://cloud.google.com/translate/docs/languages).\n\n```python\nfrom transx import TransX\n\ntx = TransX()\n\n# All these formats are valid:\ntx.current_locale = \"zh-CN\" # Hyphen format\ntx.current_locale = \"zh_CN\" # Underscore format\ntx.current_locale = \"zh\" # Language only\ntx.current_locale = \"Chinese\" # Language name\n```\n\n## \ud83d\ude80 Quick Start\n\n### \ud83d\udce5 Installation\n\n```bash\npip install transx\n```\n\n### \ud83d\udcdd Basic Usage\n\n```python\nfrom transx import TransX\n\n# Initialize with locale directory\ntx = TransX(locales_root=\"./locales\")\n\n# Basic translation\nprint(tx.tr(\"Hello\")) # Output: \u4f60\u597d\n\n# Translation with parameters\nprint(tx.tr(\"Hello {name}!\", name=\"\u5f20\u4e09\")) # Output: \u4f60\u597d \u5f20\u4e09\uff01\n\n# Context-based translation\nprint(tx.tr(\"Open\", context=\"button\")) # \u6253\u5f00\nprint(tx.tr(\"Open\", context=\"menu\")) # \u6253\u5f00\u6587\u4ef6\n\n# Switch language at runtime\ntx.current_locale = \"ja_JP\"\nprint(tx.tr(\"Hello\")) # Output: \u3053\u3093\u306b\u3061\u306f\n```\n\n### \ud83d\udd04 Advanced Parameter Substitution\n\n```python\n# Named parameters\ntx.tr(\"Welcome to {city}, {country}!\", city=\"\u5317\u4eac\", country=\"\u4e2d\u56fd\")\n\n# Positional parameters\ntx.tr(\"File {0} of {1}\", 1, 10)\n\n# Dollar sign variables (useful in shell-like contexts)\ntx.tr(\"Current user: ${USER}\") # Supports ${var} syntax\ntx.tr(\"Path: $HOME/documents\") # Supports $var syntax\n\n# Escaping dollar signs\ntx.tr(\"Price: $$99.99\") # Outputs: Price: $99.99\n```\n\n## \ud83d\udee0\ufe0f Command Line Interface\n\nTransX provides a powerful CLI for translation management:\n\n### Extract Messages\n```bash\n# Extract from a single file\ntransx extract app.py -o messages.pot\n\n# Extract from a directory\ntransx extract ./src -o messages.pot -p \"MyProject\" -v \"1.0\"\n```\n\n### Update PO Files\n```bash\n# Update or create PO files for specific languages\ntransx update messages.pot -l zh_CN ja_JP ko_KR\n\n# Auto-translate during update\ntransx update messages.pot -l zh_CN ja_JP ko_KR --translate\n```\n\n### Compile MO Files\n```bash\n# Compile a single PO file\ntransx compile locales/zh_CN/LC_MESSAGES/messages.po\n\n# Compile all PO files in a directory\ntransx compile locales\n```\n\n## \ud83c\udfaf Advanced Features\n\n### Context-Based Translations\n\n```python\n# UI Context\nprint(tx.tr(\"Open\", context=\"button\")) # \u6253\u5f00\nprint(tx.tr(\"Open\", context=\"menu\")) # \u6253\u5f00\u6587\u4ef6\n\n# Part of Speech\nprint(tx.tr(\"Post\", context=\"verb\")) # \u53d1\u5e03\nprint(tx.tr(\"Post\", context=\"noun\")) # \u6587\u7ae0\n\n# Scene Context\nprint(tx.tr(\"Welcome\", context=\"login\")) # \u6b22\u8fce\u767b\u5f55\nprint(tx.tr(\"Welcome\", context=\"home\")) # \u6b22\u8fce\u56de\u6765\n```\n\n### Error Handling\n\nTransX provides comprehensive error handling with fallback mechanisms:\n\n```python\nfrom transx import TransX\nfrom transx.exceptions import LocaleNotFoundError, TranslationError\n\n# Enable strict mode for development\ntx = TransX(strict_mode=True)\n\ntry:\n tx.load_catalog(\"invalid_locale\")\nexcept LocaleNotFoundError as e:\n print(f\"\u274c Locale error: {e.message}\")\n\ntry:\n result = tx.translate(\"Hello\", target_lang=\"invalid\")\nexcept TranslationError as e:\n print(f\"\u274c Translation failed: {e.message}\")\n```\n\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n### \ud83d\udcc1 Project Structure\n\n```\ntransx/\n\u251c\u2500\u2500 transx/ # Main package directory\n\u2502 \u251c\u2500\u2500 api/ # Public API modules\n\u2502 \u2502 \u251c\u2500\u2500 locale.py # Locale handling\n\u2502 \u2502 \u251c\u2500\u2500 mo.py # MO file operations\n\u2502 \u2502 \u251c\u2500\u2500 po.py # PO file operations\n\u2502 \u2502 \u2514\u2500\u2500 translate.py # Translation services\n\u2502 \u251c\u2500\u2500 core.py # Core functionality\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface\n\u2502 \u251c\u2500\u2500 constants.py # Constants and configurations\n\u2502 \u2514\u2500\u2500 exceptions.py # Custom exceptions\n\u251c\u2500\u2500 tests/ # Test directory\n\u251c\u2500\u2500 examples/ # Example code and usage\n\u251c\u2500\u2500 nox_actions/ # Nox automation scripts\n\u251c\u2500\u2500 docs/ # Documentation\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u2514\u2500\u2500 noxfile.py # Test automation configuration\n```\n\n## \u26a1 Performance Features\n\n- \ud83d\ude80 Uses compiled MO files for optimal speed\n- \ud83d\udcbe Automatic translation caching\n- \ud83d\udd12 Thread-safe for concurrent access\n- \ud83d\udcc9 Minimal memory footprint\n- \ud83d\udd04 Automatic PO to MO compilation\n\n\n### \ud83d\udd27 Development Setup\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/loonghao/transx.git\ncd transx\n```\n\n2. Install development dependencies:\n```bash\npip install -r requirements-dev.txt\n```\n\n### \ud83d\udd04 Development Workflow\n\nWe use [Nox](https://nox.thea.codes/) to automate development tasks. Here are the main commands:\n\n```bash\n# Run linting\nnox -s lint\n\n# Fix linting issues automatically\nnox -s lint-fix\n\n# Run tests\nnox -s pytest\n```\n\n### \ud83e\uddea Running Tests\n\nTests are written using pytest and can be run using nox:\n\n```bash\nnox -s pytest\n```\n\nFor running specific tests:\n\n```bash\n# Run a specific test file\nnox -s pytest -- tests/test_core.py\n\n# Run tests with specific markers\nnox -s pytest -- -m \"not integration\"\n```\n\n### \ud83d\udd0d Code Quality\n\nWe maintain high code quality standards using various tools:\n\n- **Linting**: We use ruff and isort for code linting and formatting\n- **Type Checking**: Static type checking with mypy\n- **Testing**: Comprehensive test suite with pytest\n- **Coverage**: Code coverage tracking with coverage.py\n- **CI/CD**: Automated testing and deployment with GitHub Actions\n\n### \ud83d\udcdd Documentation\n\nDocumentation is written in Markdown and is available in:\n- README.md: Main documentation\n- examples/: Example code and usage\n- API documentation in source code\n\n### \ud83e\udd1d Contributing Guidelines\n\n1. Fork the repository\n2. Create a new branch for your feature\n3. Make your changes\n4. Run tests and linting\n5. Submit a pull request\n\nPlease ensure your PR:\n- Passes all tests\n- Includes appropriate documentation\n- Follows our code style\n- Includes test coverage for new features\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A lightweight, zero-dependency Python library for internationalization and translation management.",
"version": "0.2.2",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "56bfa24691a32bc335aa20e64e563ee25434b6d6171ca0a303b1ead889f45d93",
"md5": "09e2c6dcdffca76cb8a803d7e3c68682",
"sha256": "2c05a1dfba4d659d7c1550285fab9d9dc1153809c2db8323add249dfd3463418"
},
"downloads": -1,
"filename": "transx-0.2.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "09e2c6dcdffca76cb8a803d7e3c68682",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": "<4.0,>=2.7",
"size": 47478,
"upload_time": "2024-12-04T17:04:26",
"upload_time_iso_8601": "2024-12-04T17:04:26.776864Z",
"url": "https://files.pythonhosted.org/packages/56/bf/a24691a32bc335aa20e64e563ee25434b6d6171ca0a303b1ead889f45d93/transx-0.2.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c0b547024db837e2b81798ada11d2ee50e1704aba1ed7ea08d53ab99f8b7d901",
"md5": "89a22061c302648bfb33d1eac54af878",
"sha256": "601b110445c405851886a6603dd89d576c33966aa95a81fece6c91ef6c72f157"
},
"downloads": -1,
"filename": "transx-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "89a22061c302648bfb33d1eac54af878",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=2.7",
"size": 42870,
"upload_time": "2024-12-04T17:04:28",
"upload_time_iso_8601": "2024-12-04T17:04:28.785339Z",
"url": "https://files.pythonhosted.org/packages/c0/b5/47024db837e2b81798ada11d2ee50e1704aba1ed7ea08d53ab99f8b7d901/transx-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-04 17:04:28",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "transx"
}
