rushwing/calibre-none-latin repository overview

⁠Calibre None Latin - Docker Container

Dockerized Calibre eBook management software with the calibre-do-not-translate-my-path plugin pre-installed to prevent path Latinization for CJK (Chinese, Japanese, Korean) and other non-Latin scripts.

⁠Source Attribution and License

⁠Base Docker Image

This project is built on the excellent work of the LinuxServer.io team:

• Base Image: linuxserver/calibre⁠
• LinuxServer.io: https://www.linuxserver.io/⁠
• Documentation: https://docs.linuxserver.io/images/docker-calibre/⁠
• GitHub: https://github.com/linuxserver/docker-calibre⁠

⁠Plugin Source

This project includes the original calibre-do-not-translate-my-path plugin by Cirn09(古明地小板):

• Original Repository: https://github.com/Cirn09/calibre-do-not-translate-my-path⁠
• Original License: GPL v3
• Original Author: Cirn09(古明地小板)
• Original Copyright: 2023-2025, Cirn09(古明地小板)

This Docker containerization project includes the original plugin with modifications as detailed below.

⁠Source Code Modifications

In compliance with GPL v3 licensing requirements, this section documents all modifications made to the original plugin source code:

⁠Modified Files:

• plugin/__init__.py - Extensively refactored (January 2025)
• plugin/ui.py - Partially refactored (January 2025)
• plugin/config.py - Unchanged from original

⁠Key Modifications Made:

⁠1. Architecture Refactoring (__init__.py)

Original Design:

• Single monolithic Hook class handling all device types
• Basic ImportError handling with no logging
• Hardcoded print statements for status messages

Modified Design:

• Modular handler system with separate classes for each hook type:
  • HookHandler - Abstract base class
  • DatabaseHookHandler - Database operations
  • USBDeviceHookHandler - USB device handling
  • SmartDeviceHookHandler - Smart device applications
  • MTPDeviceHookHandler - MTP device handling
  • SaveToDiskHookHandler - Save-to-disk operations
• HookManager class - Centralized management of all handlers
• Comprehensive logging using Python's logging module
• Type hints throughout for better code maintainability

⁠2. Enhanced Error Handling

Added:

• Proper exception handling with detailed error messages
• Graceful degradation when Calibre modules are not available
• Status reporting for handler availability
• User-friendly error dialogs in the UI

⁠3. Improved User Interface (ui.py)

Original UI:

• Basic configuration checkboxes
• Simple refresh functionality

Enhanced UI:

• Handler status checking - Shows which handlers are available
• Enhanced error reporting with proper dialog boxes
• Better progress reporting for library refresh operations
• Improved settings validation and error handling
• Type hints and documentation for all methods

⁠4. Code Quality Improvements

Added:

• Type annotations using Python's typing module
• Comprehensive docstrings for all classes and methods
• Consistent error handling patterns
• Proper logging levels (debug, info, warning, error)
• Better code organization and separation of concerns

⁠Functionality Preservation

All original functionality is preserved:

• ✅ Database filename sanitization (prevents path Latinization when adding books)
• ✅ USB device file transfer protection
• ✅ Smart device application compatibility
• ✅ MTP device path handling
• ✅ Save-to-disk operation handling
• ✅ Configuration options (Library and Send-to-device toggles)
• ✅ Plugin toolbar integration
• ✅ Library refresh functionality

⁠Benefits of Modifications

• Better Maintainability - Modular design makes code easier to understand and modify
• Enhanced Debugging - Comprehensive logging helps troubleshoot issues
• Improved Reliability - Better error handling prevents crashes
• Future Extensibility - Easy to add new device types or functionality
• Code Quality - Type hints and documentation improve development experience

⁠Modification Rationale

These modifications were made to:

1. Improve code maintainability for the Docker container environment
2. Add comprehensive error handling for better user experience
3. Enhance debugging capabilities in containerized deployments
4. Follow modern Python best practices (type hints, logging, documentation)
5. Prepare for potential future enhancements while maintaining backward compatibility

⁠No Changes to Core Logic

Important: The core path sanitization logic remains identical to the original. All modifications are structural improvements that enhance reliability and maintainability without altering the fundamental functionality.

⁠Features

⁠Container Features

• Based on LinuxServer.io Calibre⁠ - Reliable, well-maintained base image
• Web-accessible Calibre GUI via VNC with HTTP Basic Auth
• Persistent storage for library, configuration, and downloads
• Multi-architecture support (inherited from base image)
• Automatic updates and security patches (via LinuxServer.io)
• Production-ready Docker Compose configurations
• Environment-specific deployments (local development and NAS/production)

⁠Plugin Features

• Pre-installed calibre-do-not-translate-my-path plugin preventing path Latinization
• CJK Script Support - Preserves Chinese, Japanese, Korean characters in file paths
• Device Transfer Protection - Maintains non-Latin characters when sending to devices
• Library Management - Prevents path translation during book imports
• Automatic Plugin Installation - NoTrans plugin installed during container startup
• Enhanced Error Handling - Improved logging and user feedback (refactored version)

⁠Docker Compose Deployment

This project uses environment-specific configuration files (.env.local and .env.nas) to manage different deployment scenarios. Choose the appropriate method below based on your environment.

⁠Prerequisites

1. Clone this repository

git clone <your-repo-url>
cd calibre-none-latin

1. Create directory structure

mkdir -p config books downloads

⁠Method 1: Local Development Deployment

For local development and testing:

⁠Step 1: Configure Environment

# Copy the local environment template
cp .env.local .env.local.template
# Edit .env.local with your settings
nano .env.local  # or use your preferred editor

⁠Step 2: Customize .env.local

Edit .env.local file with your local configuration:

# Local Development Environment Configuration
# User and Group IDs (match your local user)
PUID=1000                    # Use: id -u
PGID=1000                    # Use: id -g

# Timezone
TZ=Asia/Shanghai             # Your timezone

# VNC Password (optional - leave empty for no password)
PASSWORD=Your_Strong_Password

# HTTP Basic Auth Username (defaults to 'abc' if not set)
CUSTOM_USER=abc              # Username for web login

# Additional Calibre CLI arguments (optional)
CLI_ARGS=

# Development settings
COMPOSE_PROJECT_NAME=calibre-none-latin-dev

⁠Step 3: Build and Deploy

# Build the image locally
./build.sh

# Start with local configuration
docker-compose -f docker-compose.local.yml up -d

⁠Method 2: NAS/Production Deployment

For production environments like Synology NAS:

⁠Step 1: Configure Environment

# Copy the NAS environment template
cp .env.nas .env.nas.template
# Edit .env.nas with your production settings
nano .env.nas  # or use your preferred editor

⁠Step 2: Customize .env.nas

Edit .env.nas file with your production configuration:

# NAS Production Environment Configuration
# User and Group IDs (match your NAS user - commonly 1000:100 on Synology)
PUID=1000                    # NAS user ID
PGID=100                     # NAS group ID (often 100 for Synology)

# Timezone
TZ=Asia/Shanghai             # Your timezone

# VNC Password (recommended for production)
PASSWORD=Your_Strong_Password

# HTTP Basic Auth Username (defaults to 'abc' if not set)
CUSTOM_USER=admin            # Change to your preferred username

# Additional Calibre CLI arguments (optional)
CLI_ARGS=

# Production settings
COMPOSE_PROJECT_NAME=calibre-none-latin-prod

⁠Step 3: Update Volume Paths

Edit docker-compose.nas.yml and update volume paths for your NAS:

volumes:
  # IMPORTANT: Update these paths to match your NAS directory structure
  - /volume1/docker/Calibre/config:/config
  - /volume2/webdav/Ebooks:/books
  - /volume4/PT3/Ebooks:/downloads

⁠Step 4: Deploy

# Deploy with NAS configuration
docker-compose -f docker-compose.nas.yml up -d

⁠Environment File Details

⁠Quick Start Commands

# Local development
./build.sh                                           # Build image
docker-compose -f docker-compose.local.yml up -d    # Start local

# NAS production  
docker-compose -f docker-compose.nas.yml up -d      # Start NAS

# View logs
docker-compose -f docker-compose.local.yml logs -f  # Local logs
docker-compose -f docker-compose.nas.yml logs -f    # NAS logs

# Stop services
docker-compose -f docker-compose.local.yml down     # Stop local
docker-compose -f docker-compose.nas.yml down       # Stop NAS

⁠Access Points

⁠Local Development (docker-compose.local.yml)

• Calibre Book Management GUI: http://localhost:8080⁠ (VNC-based desktop interface)
• Calibre-web Server: http://localhost:8081⁠ (Modern web interface, if enabled)
• Calibre Content Server: http://localhost:8181⁠ (External books access service, if enabled)

⁠NAS/Production (docker-compose.nas.yml)

• Calibre Book Management GUI: http://localhost:8082⁠ (VNC-based desktop interface)
• Calibre-web Server: http://localhost:8081⁠ (Modern web interface, if enabled)
• Calibre Content Server: http://localhost:8181⁠ (External books access service, if enabled)

⁠Port Details

⁠Login Credentials

• Username: Value of CUSTOM_USER from your .env file (default: abc)
• Password: Value of PASSWORD from your .env file
• No Authentication: Leave PASSWORD empty in .env file

Note: The NAS configuration uses port 8082 for the main GUI to avoid conflicts with other applications commonly using port 8080.

⁠Configuration

All configuration is managed through environment files (.env.local or .env.nas). See the deployment sections above for detailed setup instructions.

⁠Volume Mounts

⁠Secrets Management

For production deployments, use Docker secrets for password protection:

# Create password file
echo "your-secure-password" > config/calibre_password.txt

# Ensure proper permissions
chmod 600 config/calibre_password.txt

⁠Plugin Configuration

The NoTrans plugin is automatically installed during container startup. To configure:

1. Access Calibre GUI at the appropriate URL:
   • Local: http://localhost:8080⁠ (docker-compose.local.yml)
   • NAS: http://localhost:8082⁠ (docker-compose.nas.yml)
2. Login using your configured credentials:
   • Username: Value from CUSTOM_USER in your .env file
   • Password: Value from PASSWORD in your .env file
3. Navigate to: Preferences → Plugins → Interface Actions → NoTrans → Customize Plugin
4. Configure options:
   • ✅ Library: Prevent path translation when adding books to library
   • ✅ Send to device: Prevent translation for USB devices, MTP devices, local folders, etc.
5. Click OK and restart Calibre if prompted

⁠Plugin Features

• Library Path Protection: Prevents Latinization of book file paths when importing
• Device Transfer Protection: Maintains original script characters when sending books to devices
• Automatic Activation: Plugin hooks are applied automatically when enabled
• Toolbar Integration: Access plugin settings via NoTrans toolbar button

⁠Directory Structure

calibre-none-latin/
├── Dockerfile              # Container definition extending linuxserver/calibre
├── docker-compose.yml      # Docker Compose service configuration
├── build.sh               # Build automation script
├── README.md              # This documentation
├── CLAUDE.md              # Development guidance
├── plugin/                # NoTrans plugin source files
│   ├── __init__.py        # Main plugin logic and hooking system
│   ├── config.py          # Configuration management
│   ├── ui.py              # User interface and toolbar integration
│   ├── images/            # Plugin icon assets
│   └── translations/      # Internationalization files
├── config/                # Calibre configuration (created on first run)
├── books/                 # Ebook library storage (created on first run)
└── downloads/             # Download/export directory (created on first run)

⁠Deployment Commands

⁠Local Development

# Start the container
docker-compose -f docker-compose.local.yml up -d

# View logs
docker-compose -f docker-compose.local.yml logs -f calibre-none-latin

# Stop the container
docker-compose -f docker-compose.local.yml down

# Restart with new configuration
docker-compose -f docker-compose.local.yml restart calibre-none-latin

# Rebuild and recreate container
docker-compose -f docker-compose.local.yml up -d --build --force-recreate

⁠NAS/Production

# Start the container
docker-compose -f docker-compose.nas.yml up -d

# View logs
docker-compose -f docker-compose.nas.yml logs -f calibre-none-latin

# Stop the container
docker-compose -f docker-compose.nas.yml down

# Restart with new configuration
docker-compose -f docker-compose.nas.yml restart calibre-none-latin

# Rebuild and recreate container (if using local build)
docker-compose -f docker-compose.nas.yml up -d --build --force-recreate

⁠Troubleshooting

⁠Plugin Installation Issues

# Check if plugin was installed (replace with your compose file)
docker-compose -f docker-compose.local.yml exec calibre-none-latin ls -la /tmp/NoTrans.zip

# View installation logs
docker-compose -f docker-compose.local.yml logs calibre-none-latin | grep -i notrans

# Manually reinstall plugin
docker-compose -f docker-compose.local.yml exec calibre-none-latin /tmp/install-notrans.sh

⁠Plugin Not Visible in GUI

1. Check logs: docker-compose -f docker-compose.local.yml logs calibre-none-latin
2. Restart container: docker-compose -f docker-compose.local.yml restart calibre-none-latin
3. Manual install: Preferences → Plugins → Load plugin from file → /tmp/NoTrans.zip
4. Verify plugin status: Preferences → Plugins → Interface Actions → Look for "NoTrans"

⁠Permission Issues

# Set correct ownership
sudo chown -R 1000:1000 config books downloads

# Or update your .env file with correct IDs
echo "PUID=$(id -u)" >> .env.local
echo "PGID=$(id -g)" >> .env.local
docker-compose -f docker-compose.local.yml up -d --force-recreate

⁠Authentication Issues

1. Check username: Verify CUSTOM_USER value in your .env file
2. Check password: Verify PASSWORD value in your .env file
3. Reset credentials: Update .env file and restart container
4. Disable auth: Set PASSWORD= (empty) in .env file to disable authentication

⁠Path Translation Still Occurring

1. Access Calibre GUI at appropriate URL (see Access Points above)
2. Configure plugin: Preferences → Plugins → Interface Actions → NoTrans → Customize
3. Enable both options: ✅ Library and ✅ Send to device
4. Apply settings and restart Calibre if needed
5. Test: Try importing a book with non-Latin characters in filename

⁠Container Won't Start

# Check Docker logs (replace with your compose file)
docker-compose -f docker-compose.local.yml logs calibre-none-latin

# Verify port availability (adjust ports based on your config)
netstat -tulpn | grep -E ':(8080|8081|8181)'  # for local
netstat -tulpn | grep -E ':(8082|8081|8181)'  # for NAS

# Reset container
docker-compose -f docker-compose.local.yml down
docker-compose -f docker-compose.local.yml up -d

⁠Development and Customization

⁠Modifying the Plugin

1. Edit source files in ./plugin/ directory
2. Rebuild image: ./build.sh
3. Recreate container: docker-compose -f docker-compose.local.yml up -d --force-recreate

⁠Adding Custom Configurations

1. Mount additional config files in your docker-compose file
2. Modify Dockerfile to copy custom files
3. Update .env file with custom settings
4. Rebuild and redeploy

⁠Testing Plugin Changes

# Build and test locally
./build.sh
docker-compose -f docker-compose.local.yml up -d

# Access GUI and test functionality
# http://localhost:8080 (local development - Calibre GUI)
# http://localhost:8081 (local development - Calibre-web, if enabled)
# http://localhost:8181 (local development - Content Server, if enabled)

⁠Base Image Updates

The project uses LinuxServer.io's Calibre image as the base. Regular updates ensure security patches and improvements.

⁠Manual Update Process

# Check for and apply base image updates
./update-base-image.sh

# If update is available, test the new image
docker run --rm -p 8080:8080 calibre-none-latin:test-YYYYMMDD-HHMMSS

# If tests pass, deploy updated version
docker tag calibre-none-latin:test-YYYYMMDD-HHMMSS calibre-none-latin:latest
./deploy-dockerhub.sh v1.x  # Use appropriate version number

⁠Automated Updates (GitHub Actions)

• Monthly checks for base image updates on the 1st of each month at 2 AM UTC
• Automatic testing of updated base images
• Pull Request creation with test results and update details
• Manual workflow trigger available for immediate checks when needed

⁠Update Testing Checklist

• ✅ Container starts successfully
• ✅ NoTrans plugin is installed (/tmp/NoTrans.zip exists)
• ✅ Calibre GUI accessible via VNC
• ✅ Plugin appears in Preferences → Plugins → Interface Actions
• ✅ Plugin configuration works correctly
• ✅ Book import with non-Latin characters preserves paths

⁠Acknowledgments

This project is made possible by the excellent work of several open source projects and contributors:

⁠🐳 LinuxServer.io Team

• Exceptional Docker images with consistent quality and documentation
• Multi-architecture support and automated security updates
• Community-driven maintenance and support
• Base Image: linuxserver/calibre⁠
• Website: https://www.linuxserver.io/⁠

⁠📚 Calibre Project

• Kovid Goyal and the Calibre development team
• Open source eBook management software
• Extensive plugin architecture enabling community contributions
• Website: https://calibre-ebook.com/⁠

⁠🔧 Original Plugin Developer

• Cirn09(古明地小板) for creating the "Do Not Translate My Path" plugin
• Solving CJK path issues in Calibre for the community
• GPL v3 licensing enabling derivative works like this project
• Original Repository: https://github.com/Cirn09/calibre-do-not-translate-my-path⁠

⁠🌏 Community Impact

Special thanks to users in the Chinese, Japanese, and Korean communities who face path Latinization issues and inspired this solution.

⁠License and Compliance

⁠GPL v3 License

This project is licensed under the GNU General Public License v3.0, the same license as the original plugin.

⁠Original Work Attribution

• Original Plugin: "Do Not Translate My Path" (NoTrans)
• Original Author: Cirn09(古明地小板)
• Original Repository: https://github.com/Cirn09/calibre-do-not-translate-my-path⁠
• Original License: GPL v3
• Original Copyright: 2023-2025, Cirn09(古明地小板)

⁠Derivative Work Declaration

This Docker container project includes a derivative work of the original NoTrans plugin. In accordance with GPL v3 requirements:

1. Source Code Availability: All source code modifications are documented above and available in this repository
2. License Inheritance: This derivative work is also licensed under GPL v3
3. Modification Documentation: All changes are clearly documented in the "Source Code Modifications" section
4. Original Attribution: Full credit is given to the original author Cirn09(古明地小板)
5. License File: The complete GPL v3 license text is included in the LICENSE file

⁠Distribution Rights

Under GPL v3, you are free to:

• ✅ Use this software for any purpose
• ✅ Study and modify the source code
• ✅ Distribute copies of the original software
• ✅ Distribute modified versions (under GPL v3)

⁠Distribution Obligations

If you distribute this software or derivatives, you must:

• 📋 Include the GPL v3 license text
• 📋 Provide access to the complete source code
• 📋 Document any modifications made
• 📋 Maintain all copyright notices and attributions

⁠No Warranty

This software is provided "AS IS" without warranty of any kind, as specified in the GPL v3 license.

For the complete license terms, see the LICENSE⁠ file in this repository.