LinguaLearn - GitLite

KO | EN

gitlite — search

#mysql #sql #terminal #ai #c #web #nodejs #golang #monitoring #http

LinguaLearn

(★ 11)

LinguaLearn is a cutting-edge, full-stack language translation and learning application powered by state-of-the-art AI models. Built with React, TypeScript, and Flask, it provides seamless real-time translation, file processing, and an intuitive learning experience.

File Explorer

ZIP Download

- - pronunciation_model_training.ipynb
- lesson_generation_evaluation.py
- requirements.txt
- - app.cpython-313.pyc
- - __init__.py
  - settings.py
- - __init__.py
  - caching.py
  - rate_limiting.py
- - __init__.py
- - __init__.py
  - auth.py
  - batch_processor.py
  - language_detector.py
  - logging_config.py
- .dockerignore
- .env.example
- app.py
- auth_test.py
- DEPLOYMENT.md
- DEPLOYMENT_FIX.md
- Dockerfile
- gunicorn.conf.py
- integration_guide.py
- lazy_models.py
- main.py
- QUICKSTART.md
- requirements.txt
- runtime.txt
- simple_auth_test.py
- simple_test.py
- test_api.py
- test_enhancements.py
- test_server.py
- favicon.svg
- manifest.json
- placeholder.svg
- robots.txt
- sw.js
- - ErrorBoundary.tsx
  - Navigation.tsx
  - NavLink.tsx
  - PageSkeleton.tsx
  - SpeechSynthesis.tsx
- - AuthContext.tsx
- - use-mobile.tsx
  - use-toast.ts
  - useGamification.ts
  - useSpeechSynthesis.ts
- - ml-api.ts
  - utils.ts
- - Dashboard.tsx
  - FileTranslator.tsx
  - Home.tsx
  - ImmersionScenarios.tsx
  - Index.tsx
  - LearningPaths.tsx
  - Lessons.tsx
  - Login.tsx
  - NotFound.tsx
  - Profile.tsx
  - Pronunciation.tsx
  - Register.tsx
  - Settings.tsx
  - TextTranslator.tsx
- App.css
- App.tsx
- index.css
- main.tsx
- vite-env.d.ts
- - cli-latest
- - 001_initial_schema.sql
- config.toml
.env
.gitignore
bun.lockb
components.json
create-tables.js
deploy-function.sh
DEPLOYMENT_GUIDE.md
docker-compose.yml
Dockerfile.frontend
eslint.config.js
index.html
nginx.conf
package-lock.json
package.json
postcss.config.js
README.md
README_AI_ENHANCED.md
render.yaml
runtime.txt
start-dev.sh
start_all.sh
START_HERE.bat
tailwind.config.ts
test_file.txt
tsconfig.app.json
tsconfig.json
tsconfig.node.json
vite.config.ts

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**LinguaLearn** is a cutting-edge, full-stack language translation and learning application powered by state-of-the-art AI models. Built with React, TypeScript, and Flask, it provides seamless real-time translation, file processing, and an intuitive learning experience.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![React](https://img.shields.io/badge/react-18.0+-61DAFB.svg)](https://reactjs.org/)
[![TypeScript](https://img.shields.io/badge/typescript-5.0+-3178C6.svg)](https://www.typescriptlang.org/)

---

## 🌐 Live Demo

**🎨 Frontend Application**: [https://lingua-learn-chi.vercel.app/](https://lingua-learn-chi.vercel.app/)

Try out the live application deployed on Vercel! Experience real-time translation, file processing, and all AI-powered language learning features.

**🔧 Backend API**: [https://lingualearn-ml-backend.onrender.com/](https://lingualearn-ml-backend.onrender.com/)

Access the live ML backend service deployed on Render. Visit the root endpoint to see available API endpoints and service status.

> **Note**: First API request may take 30-60 seconds to wake up the backend service (free tier limitation).

---

## ✨ Features

### 🔤 Text Translation
- **20+ Language Pairs**: English ↔ Spanish, French, German, Italian, Russian, Chinese, Japanese, Arabic, and more
- **Auto Language Detection**: Automatically detects source language with confidence scoring
- **Real-time Translation**: Lightning-fast translations (<1 second after model warm-up)
- **Quality Metrics**: BLEU scores and confidence ratings for translation quality

### 📄 Document Translation
- **Multi-Format Support**: PDF, DOCX, TXT, and image files (up to 20MB)
- **Intelligent Chunking**: Preserves document structure while optimizing for translation accuracy
- **PDF Output**: Generates professionally formatted PDFs from translated content
- **Progress Tracking**: Real-time progress updates during large file translations
- **Batch Processing**: Efficiently handles documents with thousands of words

### 🎯 Advanced Features
- **Speech-to-Text**: Powered by Whisper model for accurate transcription
- **Pronunciation Analysis**: MFCC-based pronunciation scoring with detailed feedback
- **AI Conversation**: LLM-powered conversational assistant for language practice
- **Lesson Generation**: Personalized lesson plans using RAG (Retrieval-Augmented Generation)

### 🚀 Performance & Reliability
- **Model Caching**: LRU cache for instant subsequent translations
- **Fallback Mechanisms**: Graceful degradation ensures translations always succeed
- **Rate Limiting**: Protects API from abuse while maintaining performance
- **Error Handling**: Comprehensive error handling with detailed logging

---

## 🛠️ Tech Stack

### Frontend
- **Framework**: React 18 with TypeScript
- **Build Tool**: Vite
- **Styling**: Tailwind CSS + shadcn/ui components
- **State Management**: React Query (TanStack Query)
- **Routing**: React Router v6

### Backend (ML Service)
- **Framework**: Flask 3.0
- **ML Models**: 
  - Helsinki-NLP (Opus-MT) for fast, specialized translations
  - Whisper for speech-to-text
  - Custom MFCC + CNN for pronunciation analysis
- **ML Libraries**: PyTorch, Transformers, NLTK
- **Document Processing**: PyPDF2, python-docx, ReportLab
- **Caching**: Flask-Caching with LRU eviction
- **Security**: JWT authentication, Flask-Limiter for rate limiting

### Infrastructure
- **Database**: Supabase (PostgreSQL)
- **API Protocols**: RESTful HTTP/JSON
- **CORS**: Configured for localhost development

---

## 📦 Installation

### Prerequisites
- **Python**: 3.11+ (3.13 recommended)
- **Node.js**: 18+ with npm
- **Git**: For cloning the repository

### Quick Start

1. **Clone the Repository**
```bash
git clone https://github.com/josephkamau32/LinguaLearn.git
cd LinguaLearn
```

2. **Backend Setup**
```bash
cd ml-service

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Download NLTK data
python -c "import nltk; nltk.download('punkt'); nltk.download('averaged_perceptron_tagger')"

# Start ML service
python app.py
```

The backend will run on `http://localhost:5000`

3. **Frontend Setup** (in a new terminal)
```bash
cd LinguaLearn

# Install dependencies
npm install

# Start development server
npm run dev
```

The frontend will run on `http://localhost:3000`

### One-Command Startup (Windows)
```bash
START_HERE.bat
```

This script automatically:
- Installs all dependencies
- Starts the ML service in a separate window
- Starts the frontend development server
- Opens the app in your browser

---

## 🎮 Usage

### Text Translation

1. Navigate to **Text Translator**
2. Enter text or paste content
3. Select target language (source auto-detected)
4. Click **Translate**
5. View translated text with confidence score

**Example**:
```
Input: "Good morning, how are you?"
Target: Spanish
Output: "Buenos días, ¿cómo estás?"
Confidence: 92%
```

### File Translation

1. Navigate to **File Translator**
2. Upload a document (PDF, DOCX, TXT, or image)
3. Select target language
4. Click **Translate**
5. Monitor real-time progress
6. Download translated PDF

**Supported Formats**:
- PDF documents (extracts and translates text)
- DOCX files (Microsoft Word)
- Plain text files (.txt)
- Images with text (OCR → Translation)

**Output**:
- PDF/DOCX inputs → Professional PDF output
- TXT inputs → Plain text output

---

## 🌐 API Documentation

### Base URLs

**Local Development:**
```
http://localhost:5000
```

**Production (Render):**
```
https://lingualearn-ml-backend.onrender.com
```

### Endpoints

#### Translate Text
```http
POST /api/translate-text
Content-Type: application/json

{
  "text": "Hello world",
  "source_lang": "auto",  // or specific language code
  "target_lang": "es"
}
```

**Response**:
```json
{
  "translated_text": "Hola mundo",
  "confidence": 0.95,
  "model_used": "en-es",
  "processing_time": 0.234,
  "detected_language": "en",
  "detection_confidence": 0.98
}
```

#### Translate File
```http
POST /api/translate-file
Content-Type: multipart/form-data

file: <binary>
targetLanguage: "es"
```

**Response**:
```json
{
  "task_id": "uuid-string",
  "status": "processing",
  "progress_url": "/api/translation/progress/{task_id}",
  "download_url": "/api/translation/download/{task_id}"
}
```

#### Check Translation Progress
```http
GET /api/translation/progress/{task_id}
```

**Response**:
```json
{
  "status": "completed",
  "progress": 100,
  "message": "Translation completed!",
  "total_chunks": 12,
  "current_chunk": 12
}
```

#### Download Translated File
```http
GET /api/translation/download/{task_id}
```

Returns the translated file as a downloadable attachment.

### Language Codes

| Code | Language | Code | Language |
|------|----------|------|----------|
| `en` | English | `es` | Spanish |
| `fr` | French | `de` | German |
| `it` | Italian | `pt` | Portuguese |
| `ru` | Russian | `zh` | Chinese |
| `ja` | Japanese | `ko` | Korean |
| `ar` | Arabic | `hi` | Hindi |
| `nl` | Dutch | `pl` | Polish |
| `sv` | Swedish | `fi` | Finnish |
| `da` | Danish | `no` | Norwegian |
| `tr` | Turkish | `el` | Greek |
| `he` | Hebrew | `th` | Thai |
| `uk` | Ukrainian | `cs` | Czech |

---

## 📁 Project Structure

```
LinguaLearn/
├── ml-service/                 # Backend ML API
│   ├── app.py                 # Main Flask application
│   ├── config/                # Configuration files
│   ├── models/                # ML model implementations
│   │   ├── translation/       # Translation models
│   │   ├── speech_to_text/   # Whisper STT
│   │   ├── pronunciation/     # Pronunciation analysis
│   │   └── rag/              # RAG for lesson generation
│   ├── middleware/            # Auth, rate limiting, caching
│   ├── utils/                 # Utility functions
│   │   ├── language_detector.py  # Enhanced detection
│   │   └── batch_processor.py    # File chunking
│   └── requirements.txt       # Python dependencies
│
├── src/                       # Frontend React app
│   ├── components/            # React components
│   ├── pages/                # Page components
│   ├── lib/                  # Utilities
│   ├── hooks/                # Custom React hooks
│   └── types/                # TypeScript type definitions
│
├── public/                    # Static assets
├── START_HERE.bat            # Quick start script (Windows)
├── start_all.sh              # Quick start script (Unix)
├── package.json              # Node.js dependencies
└── README.md                 # This file
```

---

## 🔧 Configuration

### Environment Variables

Create a `.env` file in the root directory:

```env
# Frontend
VITE_ML_SERVICE_URL=http://localhost:5000

# Backend (ml-service/.env)
SECRET_KEY=your-secret-key-here
JWT_SECRET_KEY=your-jwt-secret
LOG_LEVEL=INFO
LOG_FILE=app.log

# Supabase (optional)
SUPABASE_URL=your-supabase-url
SUPABASE_KEY=your-supabase-key
```

### Rate Limiting

Default limits (configurable in `config/settings.py`):
- Translation: 100 requests/minute
- Speech-to-Text: 20 requests/minute
- File Translation: 10 requests/minute

---

## 🧪 Testing

### Run Tests
```bash
# Backend tests
cd ml-service
pytest tests/

# Frontend tests
npm test
```

### Test Coverage
```bash
pytest --cov=. tests/
```

---

## 🚀 Performance

### Translation Speed
| Text Length | First Translation | Cached | 
|------------|-------------------|--------|
| < 50 words | < 1s | < 0.5s |
| 50-200 words | 1-2s | < 1s |
| 200+ words | 2-5s | 1-2s |

*Note: First translation includes ~7s model loading time*

### File Translation
| File Size | Processing Time |
|-----------|----------------|
| < 1MB | 10-30s |
| 1-5MB | 30-90s |
| 5-20MB | 90-300s |

---

## 🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

### Development Guidelines
- Follow PEP 8 for Python code
- Use ESLint/Prettier for TypeScript/React
- Write tests for new features
- Update documentation as needed

---

## 🐛 Known Issues & Limitations

### Current Limitations
1. **Language Coverage**: 20+ pairs (common languages only)
   - Missing: Swahili, Croatian, Tamil, Bengali, rare languages
   - Workaround: Falls back to English-Spanish

2. **Model Loading**: 7-10 second delay on first use of each language pair
   - Subsequent translations are fast (<1s)

3. **File Size**: 20MB limit for uploaded files

4. **PDF Recreation**: Extracts and translates text, doesn't preserve original formatting
   - Output is a clean, new PDF with translated text

### Planned Enhancements (V2.0)
- ✅ M2M100 model integration (100+ languages)
- ✅ Enhanced language detector with confidence scoring
- ✅ Smart batch processor for 2-3x faster files
- ⏳ GPU acceleration support
- ⏳ Model quantization for faster inference
- ⏳ Original PDF layout preservation

---

## 📊 Architecture

### Translation Flow

```
User Input
    ↓
Language Detection (auto or manual)
    ↓
Model Selection (Helsinki-NLP)
    ├→ Model in Cache? → Use cached model
    └→ Not in Cache? → Load model (~7s)
    ↓
Translation (PyTorch inference)
    ↓
Quality Metrics Calculation
    ↓
Response with translated text + metadata
```

### File Translation Flow

```
File Upload (PDF/DOCX/TXT/Image)
    ↓
Text Extraction (PyPDF2/python-docx/OCR)
    ↓
Intelligent Chunking (400 chars/chunk)
    ↓
Parallel Translation (all chunks)
    ↓
Assembly & PDF Generation (ReportLab)
    ↓
Download
```

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 👨‍💻 Author

**Joseph Kamau**
- GitHub: [@josephkamau32](https://github.com/josephkamau32)
- Repository: [LinguaLearn](https://github.com/josephkamau32/LinguaLearn)

---

## 🙏 Acknowledgments

- **Helsinki-NLP** for the Opus-MT translation models
- **OpenAI** for Whisper speech-to-text model
- **Meta AI** for M2M100 multilingual model
- **Hugging Face** for the Transformers library
- **shadcn/ui** for beautiful UI components

---

## 📞 Support

For issues, questions, or suggestions:
- Open an issue on [GitHub Issues](https://github.com/josephkamau32/LinguaLearn/issues)
- Contact: iamjosephkamau@gmail.com

---

## 🎯 Roadmap

### ✅ Completed
- [x] Text translation (20+ languages)
- [x] File translation (PDF, DOCX, TXT)
- [x] Auto language detection
- [x] Model caching
- [x] Rate limiting
- [x] PDF output generation
- [x] Progress tracking for files

### 🔜 Coming Soon
- [ ] M2M100 integration (100+ languages)
- [ ] Enhanced language detector UI
- [ ] Batch file processing
- [ ] Translation history
- [ ] User accounts and saved translations
- [ ] Mobile app (React Native)
- [ ] Browser extension

---

<div align="center">

**Made with ❤️ by Joseph Kamau**

⭐ Star this repo if you find it useful!

</div>