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.
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.
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.
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
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.
- 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
- 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
- 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
- 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
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
Choose the method that works best for you:
One command to rule them all!
docker-compose upThen 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
Double-click to launch!
-
Build the app:
npm run electron:build:win # Windows npm run electron:build:linux # Linux
-
Find the installer in
electron/dist/ -
Install and double-click the icon
โ
Native desktop application
โ
Auto-starts backend and frontend
โ
System tray integration
โ
Single executable
One command, one server:
npm startThen open: http://localhost:3000
โ
Backend serves frontend
โ
One process to manage
โ
Production-ready
For developers with hot-reload:
npm run devRuns backend (port 5000) and frontend (port 3000) separately.
If you have path encoding issues (accented characters like "รrea"):
- Open Command Prompt (Win+R โ
cmdโ Enter) - 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:3000Note: Replace the path with your actual project location.
- 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!)
# 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.shThe installer will:
- Check Node.js and npm versions
- Install all dependencies
- Create necessary directories
- Generate launcher scripts
- Create a desktop shortcut
Prerequisites:
- Node.js 18+ (Download here)
- Python 3.6+ (Download here) - Required for compiling
better-sqlite3 - Visual Studio Build Tools (Download here) - Required for compiling native modules
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.ps1Important 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.mdandUSAGE_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
Already have the app installed? Update easily:
Ubuntu/Linux:
./update.shWindows:
.\update.ps1The 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!
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- Launch the Application
- Ubuntu: Run
./launch.shor 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
- Ubuntu: Run
๐ก 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:3000for the frontend andhttp://localhost:5000for the backend). Always refresh your browser after restarting the application!
-
Configure API Settings (First Time)
- Go to the Settings tab
- Enter your DeepL and/or OpenAI API key
- Test the connection
- Save settings
-
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
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
- Visit deepl.com/pro-api
- Sign up for a free or paid account
- Go to account settings
- Copy your authentication key
- Free tier: 500,000 characters/month
- Visit platform.openai.com
- Create an account
- Navigate to API Keys section
- Create a new secret key
- Copy and save securely
- Pricing: Pay per token used
-
Manual Entry
- Go to Glossary tab
- Enter source and target terms
- Select languages
- Click "Add Entry"
-
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
- Prepare CSV file with columns:
-
Export Glossary
- Click "Export CSV"
- Use filters to export specific language pairs
- Save for backup or sharing
- 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
Create backend/.env:
PORT=5000
FRONTEND_URL=http://localhost:3000
NODE_ENV=developmentConfigure in Settings tab or set default:
backend/outputs/
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
- Free: 500,000 characters/month
- Pro: Starting at 5.99โฌ/month for 1M characters
- Rate Limits: 20 requests/minute (Free)
- 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
Example for a 100,000-word book:
- DeepL: ~โฌ6-10 (depending on plan)
- GPT-3.5: ~$2-3
- GPT-4: ~$40-50
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/
โโโ src/
โ โโโ components/ # Tab components
โ โโโ App.jsx # Main application
โ โโโ App.css # Styling
โโโ public/ # Static assets
settings: API keys and configurationglossary: Custom term translationstranslation_jobs: Job trackingtranslation_chunks: Individual text chunks with cacheapi_usage: Daily usage tracking
# Backend (with auto-reload)
cd backend
npm run dev
# Frontend (with HMR)
cd frontend
npm run dev# Frontend
cd frontend
npm run build
# Backend stays the same (Node.js)-
New Translation API
- Add service to
backend/services/translationService.js - Update frontend API provider options
- Add service to
-
New Document Format
- Add parser to
backend/services/documentParser.js - Add builder to
backend/services/documentBuilder.js
- Add parser to
# Check Node.js version
node -v # Should be 18+
# Reinstall dependencies
cd backend
rm -rf node_modules package-lock.json
npm installcd frontend
rm -rf node_modules package-lock.json
npm install- 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
# Reset database (WARNING: Deletes all data)
rm backend/data/translator.db
# Restart backend to recreate- Check API key in Settings
- Test API connection
- Verify document format is supported
- Check API usage limits
- Try smaller chunk size
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.ps1Permanent Fix:
- Copy
.wslconfigtoC:\Users\YourUsername\.wslconfig - Set memory limit (e.g.,
memory=4GBfor 16GB RAM systems) - Run
wsl --shutdown - Restart Docker Desktop
See: WSL_MEMORY_FIX.md for detailed guide.
This project is provided as-is for personal use only. See copyright notice above.
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
For issues and questions:
- Check this README thoroughly
- Review error messages in terminal
- Check API provider documentation
- Verify API keys and limits
- 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
- Start Small: Test with a short document first
- Check Limits: Monitor API usage regularly
- Backup Glossary: Export your glossary periodically
- Review Translations: AI isn't perfect, always review output
- Respect Copyright: Only translate documents you have rights to
- Save API Keys: Use Settings tab to save credentials securely
DeepL supports:
- ๐ฌ๐ง English, ๐ช๐ธ Spanish, ๐ซ๐ท French, ๐ฉ๐ช German, ๐ฎ๐น Italian
- ๐ต๐น Portuguese, ๐ณ๐ฑ Dutch, ๐ต๐ฑ Polish, ๐ท๐บ Russian
- ๐ฏ๐ต Japanese, ๐จ๐ณ Chinese, and more
OpenAI supports 95+ languages including all major world languages.
- Use Glossaries: Define technical or domain-specific terms
- Choose Right API: DeepL for European languages, GPT-4 for context
- Review & Edit: AI translations need human review
- Split Large Docs: Better results with smaller sections
- Consistent Terminology: Use glossary for consistency
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.
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.