Skip to content
This repository was archived by the owner on Jan 28, 2026. It is now read-only.

About

Translator for e-books

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

84 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

CatScribe Translate โ€” Prototype

This repository contains an early prototype created for research and learning.

โœ… A commercial-grade rewrite is currently in development in a private repository. Status: archived / no active development.

A powerful desktop application for translating documents (EPUB, DOCX, PDF) using AI translation services like DeepL and OpenAI. Features include intelligent document splitting, glossary management, progress tracking, and automatic retry on failures.

๐ŸŽ“ About This Project

This project is primarily for educational purposes and study.

This application was developed as a learning project to explore:

  • Document parsing and processing (EPUB, DOCX, PDF)
  • AI translation API integration (DeepL, OpenAI, Google Translate)
  • Real-time progress tracking with WebSockets
  • Database management with SQLite
  • Frontend/Backend architecture with React and Node.js

AI-Assisted Development: This project was developed with the assistance of AI tools (including Cursor AI and ChatGPT) to help with code generation, debugging, and implementation. The development process involved collaboration between human developers and AI assistants to create a functional translation application.

Purpose: This tool is intended for personal use, learning, and experimentation. It demonstrates how modern web technologies can be combined to create practical desktop applications.

โš ๏ธ Important Copyright Notice

THIS SOFTWARE IS FOR PERSONAL USE ONLY

  • โœ… Allowed: Translating documents you own or have permission to translate for personal use
  • โŒ Not Allowed:
    • Commercial use or redistribution
    • Translating copyrighted material without permission
    • Violating intellectual property rights
    • Circumventing DRM or access controls

You are responsible for complying with all applicable laws and respecting copyright holders' rights.

๐Ÿ”’ Privacy & Local Storage

Your data stays on your computer:

  • โœ… 100% Local Storage: All translations, settings, and API keys are stored in an SQLite database on your device
  • โœ… No Cloud Sync: Your documents never leave your computer (except when sent to translation APIs you configure)
  • โœ… No Telemetry: We don't track usage, collect analytics, or send any data to external servers
  • โœ… Encrypted Keys: API keys are encrypted with AES-256 before storage
  • โœ… Full Control: You can delete all data by removing the database file at any time

Data Location:

  • Database: backend/database/translations.db
  • Uploads: backend/uploads/
  • Outputs: backend/outputs/

What gets sent to external services:

  • Only the text chunks you choose to translate are sent to your selected translation API (DeepL, OpenAI, or Google)
  • API keys are transmitted directly to the respective services for authentication
  • No other data leaves your computer

๐Ÿ” Security Features

NEW in v1.0.0: Enhanced security for your API keys!

  • ๐Ÿ”’ AES-256 Encryption: All API keys encrypted before storage
  • ๐Ÿ”Œ Connection Testing: Test API keys before saving
  • ๐Ÿงช Automated Tests: System health checks on startup
  • ๐Ÿ›ก๏ธ Secure Storage: SQLite with encrypted sensitive data
  • ๐Ÿ‘๏ธ System Monitoring: Real-time health and test status
  • ๐Ÿ” Password Fields: Keys never visible in UI

See SECURITY.md for complete security documentation.

โœจ Features

๐ŸŒ Translation

  • Multiple Format Support: EPUB, DOCX, PDF input and output
  • AI-Powered Translation: DeepL, OpenAI (GPT-3.5/GPT-4), Google Translate, and LibreTranslate (Local, FREE!) integration
  • ๐Ÿ  Local Translation: Use LibreTranslate for 100% free, unlimited, private translations (no internet required after setup)
  • ๐Ÿ†“ No API Key Required: Use Google Translate or LibreTranslate for free without registration
  • Smart Document Splitting: Automatically chunks large documents respecting API limits
  • Progress Tracking: Real-time progress updates with WebSocket support
  • Automatic Retry: Failed chunks are cached and can be retried
  • API Limit Monitoring: Track usage and avoid exceeding rate limits

๐Ÿ“– Glossary Management

  • Custom Glossary: Define your own term translations
  • CSV Import/Export: Easy bulk management of glossary entries
  • Language-Specific: Separate glossaries for different language pairs
  • Category Organization: Organize terms by category
  • Automatic Application: Glossary terms are automatically used during translation
  • Local Model Support: Works with LibreTranslate via pre/post-processing

โš™๏ธ Settings

  • API Configuration: Save and test API credentials
  • Model Selection: Choose between different OpenAI models
  • Output Directory: Configure where translated documents are saved
  • Chunk Size Adjustment: Optimize translation performance

๐Ÿ’พ Caching & Reliability

  • SQLite Database: All data stored locally
  • Translation Cache: Resume interrupted translations
  • Error Handling: Graceful degradation on API errors
  • Rate Limit Management: Automatic delays to respect API limits

๐Ÿงช Built-in Testing

The application includes comprehensive automated tests that run on startup:

  • โœ… Database connectivity and schema validation
  • โœ… Encryption/decryption functionality
  • โœ… Settings CRUD operations
  • โœ… API key encryption verification
  • โœ… Glossary operations
  • โœ… Translation job management
  • โœ… Document parsing
  • โœ… API usage tracking

View test results: Click "๐Ÿ”ง System Status" button in the header

๐Ÿš€ Quick Start

Choose the method that works best for you:

Method 1: Docker (Easiest - Recommended) ๐Ÿณ

One command to rule them all!

docker-compose up

Then open: http://localhost:3000

โœ… Works identically on Windows, Linux, and Mac
โœ… No Node.js installation needed
โœ… Includes LibreTranslate (local translation)
โœ… Isolated environment

๐Ÿ“– Full guide: DOCKER_GUIDE.md


Method 2: Electron Desktop App ๐Ÿ–ฅ๏ธ

Double-click to launch!

  1. Build the app:

    npm run electron:build:win  # Windows
    npm run electron:build:linux  # Linux
  2. Find the installer in electron/dist/

  3. Install and double-click the icon

โœ… Native desktop application
โœ… Auto-starts backend and frontend
โœ… System tray integration
โœ… Single executable


Method 3: Single Server (Simple) ๐Ÿ“ฆ

One command, one server:

npm start

Then open: http://localhost:3000

โœ… Backend serves frontend
โœ… One process to manage
โœ… Production-ready


Method 4: Development Mode ๐Ÿ› ๏ธ

For developers with hot-reload:

npm run dev

Runs backend (port 5000) and frontend (port 3000) separately.


Method 5: Manual (Windows - If other methods fail)

If you have path encoding issues (accented characters like "รrea"):

  1. Open Command Prompt (Win+R โ†’ cmd โ†’ Enter)
  2. Paste this command:
cd /d "C:\Users\YOUR_USER\path\to\smart-book-translator" && start "Backend" cmd /k "cd /d backend && npm start" && timeout /t 3 /nobreak >nul && start "Frontend" cmd /k "cd /d frontend && npm run dev" && timeout /t 10 /nobreak >nul && start http://localhost:3000

Note: Replace the path with your actual project location.

Prerequisites

  • Node.js 18+ (Download here)
  • Optional: Docker Desktop for local translation (Download here)
  • Optional: API keys from DeepL and/or OpenAI (Google Translate and LibreTranslate are FREE!)

Ubuntu/Linux Installation

# Clone or download the repository
cd smart-book-translator

# Run the installation script
chmod +x install-ubuntu.sh
./install-ubuntu.sh

# Start the application
./run.sh

The installer will:

  • Check Node.js and npm versions
  • Install all dependencies
  • Create necessary directories
  • Generate launcher scripts
  • Create a desktop shortcut

Windows Installation

Prerequisites:

Quick Setup:

# Open PowerShell as Administrator
cd smart-book-translator

# Enable script execution (if needed)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Install Python (if needed)
.\install-python-windows.ps1
# IMPORTANT: Close and reopen PowerShell after installing Python!

# Configure Python for npm
.\fix-python-config.ps1

# Run the installation script
.\install-windows.ps1

# Start the application
.\run.bat
# or
.\run.ps1

Important Notes:

  • When installing Python, check "Add Python to PATH" โœ…
  • After installing Build Tools, restart your computer
  • If you get Python errors, see the troubleshooting sections in INSTALLATION_GUIDE.md and USAGE_GUIDE.md

The installer will:

  • Check Node.js and npm versions
  • Verify Python installation
  • Install all dependencies
  • Create necessary directories
  • Generate launcher scripts
  • Create a desktop shortcut

Updating to Latest Version

Already have the app installed? Update easily:

Ubuntu/Linux:

./update.sh

Windows:

.\update.ps1

The update script will:

  • โœ… Backup your database (translations, glossary, settings)
  • โœ… Pull latest code changes (if using git)
  • โœ… Update all dependencies
  • โœ… Preserve your data and API keys
  • โœ… Run tests to verify everything works

Note: Your settings, glossary, and translation history are preserved during updates!

Manual Installation

If the automatic installer doesn't work:

# Install backend dependencies
cd backend
npm install
cp .env.example .env
mkdir -p uploads outputs data temp
cd ..

# Install frontend dependencies
cd frontend
npm install
cd ..

# Start backend (in one terminal)
cd backend
npm start

# Start frontend (in another terminal)
cd frontend
npm run dev

๐ŸŽฏ Usage

Quick Start

  1. Launch the Application
    • Ubuntu: Run ./launch.sh or click "Smart Book Translator" in your applications menu
    • Windows: Double-click the desktop shortcut or run run.bat
    • The application will open in your browser automatically

๐Ÿ’ก Tip: If you see "Backend Offline", make sure you're accessing the correct URL. After starting, the terminal will show the correct URLs (usually http://localhost:3000 for the frontend and http://localhost:5000 for the backend). Always refresh your browser after restarting the application!

  1. Configure API Settings (First Time)

    • Go to the Settings tab
    • Enter your DeepL and/or OpenAI API key
    • Test the connection
    • Save settings
  2. Translate a Document

    • Go to the Translation tab
    • Upload your document (drag & drop or click to browse)
    • Select source and target languages
    • Choose translation API
    • Enter API key (or use saved one)
    • Click "Start Translation"
    • Monitor progress in real-time
    • Download when complete

Getting API Keys

๐Ÿ†“ Google Translate (FREE - Recommended for Testing!)

No API key needed! Just select "Google Translate" in the app and start translating.

Perfect for:

  • Testing the application
  • Occasional translations
  • Learning how it works
  • Users without API accounts

Limitations:

  • May be rate-limited for very heavy usage
  • Not recommended for large-scale production use
  • Free service with no guarantees

DeepL API

  1. Visit deepl.com/pro-api
  2. Sign up for a free or paid account
  3. Go to account settings
  4. Copy your authentication key
  5. Free tier: 500,000 characters/month

OpenAI API

  1. Visit platform.openai.com
  2. Create an account
  3. Navigate to API Keys section
  4. Create a new secret key
  5. Copy and save securely
  6. Pricing: Pay per token used

Using the Glossary

  1. Manual Entry

    • Go to Glossary tab
    • Enter source and target terms
    • Select languages
    • Click "Add Entry"
  2. CSV Import

    • Prepare CSV file with columns:
      Source Term, Target Term, Source Language, Target Language, Category
      hello,hola,en,es,Greetings
      world,mundo,en,es,Common
      
    • Click "Import CSV"
    • Select your file
  3. Export Glossary

    • Click "Export CSV"
    • Use filters to export specific language pairs
    • Save for backup or sharing

Managing Translations

  • View Progress: Watch real-time updates as chunks are translated
  • Retry Failed Chunks: If some chunks fail, click "Retry" to reprocess them
  • Download Results: Click "Download" once translation is complete
  • Check API Usage: Monitor your daily usage to avoid limits

๐Ÿ› ๏ธ Configuration

Environment Variables

Create backend/.env:

PORT=5000
FRONTEND_URL=http://localhost:3000
NODE_ENV=development

Output Directory

Configure in Settings tab or set default:

backend/outputs/

Chunk Size

Adjust in Settings (default: 3000 characters):

  • Smaller chunks = more API calls, better error handling
  • Larger chunks = fewer API calls, risk hitting limits
  • Recommended: 3000-5000

๐Ÿ“Š API Limits & Pricing

DeepL

  • Free: 500,000 characters/month
  • Pro: Starting at 5.99โ‚ฌ/month for 1M characters
  • Rate Limits: 20 requests/minute (Free)

OpenAI

  • GPT-3.5 Turbo: $0.0015 per 1K tokens (~750 words)
  • GPT-4: $0.03 per 1K tokens (~750 words)
  • GPT-4 Turbo: $0.01 per 1K tokens
  • Rate Limits: Varies by account tier

Cost Estimation

Example for a 100,000-word book:

  • DeepL: ~โ‚ฌ6-10 (depending on plan)
  • GPT-3.5: ~$2-3
  • GPT-4: ~$40-50

๐Ÿ—๏ธ Architecture

Backend (Node.js + Express)

backend/
โ”œโ”€โ”€ database/          # SQLite database initialization
โ”œโ”€โ”€ models/           # Data models (Jobs, Glossary, Settings)
โ”œโ”€โ”€ services/         # Document parsing, translation, building
โ”œโ”€โ”€ routes/           # API endpoints
โ”œโ”€โ”€ uploads/          # Temporary file storage
โ”œโ”€โ”€ outputs/          # Translated documents
โ””โ”€โ”€ server.js         # Main server file

Frontend (React + Vite)

frontend/
โ”œโ”€โ”€ src/
โ”‚   โ”œโ”€โ”€ components/   # Tab components
โ”‚   โ”œโ”€โ”€ App.jsx       # Main application
โ”‚   โ””โ”€โ”€ App.css       # Styling
โ””โ”€โ”€ public/           # Static assets

Database Schema

  • settings: API keys and configuration
  • glossary: Custom term translations
  • translation_jobs: Job tracking
  • translation_chunks: Individual text chunks with cache
  • api_usage: Daily usage tracking

๐Ÿ”ง Development

Running in Development Mode

# Backend (with auto-reload)
cd backend
npm run dev

# Frontend (with HMR)
cd frontend
npm run dev

Building for Production

# Frontend
cd frontend
npm run build

# Backend stays the same (Node.js)

Adding New Features

  1. New Translation API

    • Add service to backend/services/translationService.js
    • Update frontend API provider options
  2. New Document Format

    • Add parser to backend/services/documentParser.js
    • Add builder to backend/services/documentBuilder.js

๐Ÿ› Troubleshooting

Backend Won't Start

# Check Node.js version
node -v  # Should be 18+

# Reinstall dependencies
cd backend
rm -rf node_modules package-lock.json
npm install

Frontend Won't Start

cd frontend
rm -rf node_modules package-lock.json
npm install

API Errors

  • 401 Unauthorized: Check API key
  • 429 Rate Limit: Wait before retrying, check usage
  • Connection Error: Check internet connection
  • Timeout: Large documents may take time, be patient

Database Issues

# Reset database (WARNING: Deletes all data)
rm backend/data/translator.db
# Restart backend to recreate

Translation Failures

  1. Check API key in Settings
  2. Test API connection
  3. Verify document format is supported
  4. Check API usage limits
  5. Try smaller chunk size

High WSL Memory Usage (Windows)

Problem: vmmemWSL consuming 10GB+ RAM after closing the application.

Quick Fix:

# Stop Docker containers and free WSL memory
.\stop-docker.ps1

# Or complete cleanup (stops everything)
.\stop-all.ps1

Permanent Fix:

  1. Copy .wslconfig to C:\Users\YourUsername\.wslconfig
  2. Set memory limit (e.g., memory=4GB for 16GB RAM systems)
  3. Run wsl --shutdown
  4. Restart Docker Desktop

See: WSL_MEMORY_FIX.md for detailed guide.

๐Ÿ“ License

This project is provided as-is for personal use only. See copyright notice above.

๐Ÿค Contributing

As this is a personal use tool, please ensure any contributions:

  • Maintain the copyright notice
  • Don't enable piracy or illegal use
  • Follow ethical AI usage guidelines
  • Respect API provider terms of service

๐Ÿ“ž Support

For issues and questions:

  1. Check this README thoroughly
  2. Review error messages in terminal
  3. Check API provider documentation
  4. Verify API keys and limits

๐Ÿ” Security & Privacy

  • Local Storage: All data stored locally in SQLite
  • No Telemetry: No data sent to third parties except APIs
  • API Keys: Stored locally, never shared
  • Documents: Uploaded files deleted after processing
  • Temporary Files: Cleared automatically

๐ŸŒŸ Best Practices

  1. Start Small: Test with a short document first
  2. Check Limits: Monitor API usage regularly
  3. Backup Glossary: Export your glossary periodically
  4. Review Translations: AI isn't perfect, always review output
  5. Respect Copyright: Only translate documents you have rights to
  6. Save API Keys: Use Settings tab to save credentials securely

๐Ÿ“š Supported Languages

DeepL supports:

  • ๐Ÿ‡ฌ๐Ÿ‡ง English, ๐Ÿ‡ช๐Ÿ‡ธ Spanish, ๐Ÿ‡ซ๐Ÿ‡ท French, ๐Ÿ‡ฉ๐Ÿ‡ช German, ๐Ÿ‡ฎ๐Ÿ‡น Italian
  • ๐Ÿ‡ต๐Ÿ‡น Portuguese, ๐Ÿ‡ณ๐Ÿ‡ฑ Dutch, ๐Ÿ‡ต๐Ÿ‡ฑ Polish, ๐Ÿ‡ท๐Ÿ‡บ Russian
  • ๐Ÿ‡ฏ๐Ÿ‡ต Japanese, ๐Ÿ‡จ๐Ÿ‡ณ Chinese, and more

OpenAI supports 95+ languages including all major world languages.

๐ŸŽ“ Tips for Better Translations

  1. Use Glossaries: Define technical or domain-specific terms
  2. Choose Right API: DeepL for European languages, GPT-4 for context
  3. Review & Edit: AI translations need human review
  4. Split Large Docs: Better results with smaller sections
  5. Consistent Terminology: Use glossary for consistency

๐Ÿ“ฑ Mobile Version

Interested in using this on mobile? Check MOBILE_VERSION.md for:

  • PWA (Progressive Web App) - Works now!
  • iOS/Android native apps (Capacitor)
  • React Native options
  • Complete feasibility analysis

TL;DR: Responsive web version already works on mobile! Native apps possible with Capacitor.

๐Ÿ’ผ Commercial Use

Want to use this commercially? See COMMERCIAL_CONSIDERATIONS.md for:

  • Legal requirements
  • API Terms of Service compliance
  • Licensing considerations
  • Cost breakdown
  • Step-by-step commercialization guide

TL;DR: Personal use is fine as-is. Commercial use requires paid APIs, proper legal docs, and licensing.


Version: 1.0.0
Last Updated: November 2025
Node.js: 18+ Required

Made with โค๏ธ for personal document translation needs.

About

Translator for e-books

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages