README.md

---
license: mit
sdk: docker
colorTo: blue
---
# 🌍 سرویس ترجمه چندزبانه M2M100

سرویس ترجمه پیشرفته مبتنی بر FastAPI که از مدل M2M100 فیسبوک برای ترجمه بین بیش از 100 زبان مختلف استفاده می‌کند.

## ✨ ویژگی‌ها

- **ترجمه چندزبانه**: پشتیبانی از بیش از 100 زبان
- **کش هوشمند**: ذخیره نتایج ترجمه برای بهبود سرعت
- **تقسیم متن**: پردازش خودکار متون طولانی
- **پردازش پس‌زمینه**: ترجمه متون سنگین در پس‌زمینه
- **پیگیری پیشرفت**: مشاهده وضعیت ترجمه به صورت real-time
- **یکپارچگی WordPress**: سازگار با سیستم‌های مدیریت محتوا
- **GPU/CPU**: پشتیبانی از هر دو حالت

## 🚀 راه‌اندازی سریع

### روش 1: Hugging Face Spaces
1. فایل‌ها را در یک Space جدید قرار دهید
2. Space به صورت خودکار راه‌اندازی می‌شود

### روش 2: محلی
```bash
# کلون کردن پروژه
git clone [repository-url]
cd multilingual-translator

# نصب وابستگی‌ها
pip install -r requirements.txt

# اجرای سرویس
python app.py
```

### روش 3: Docker
```bash
docker build -t multilingual-translator .
docker run -p 7860:7860 multilingual-translator
```

## 📋 API Endpoints

### 🏠 اصلی
- `GET /` - صفحه اصلی و راهنما
- `GET /api/health` - وضعیت سلامت سرویس
- `GET /api/server-status` - وضعیت کلی سرور

### 🔄 ترجمه
- `POST /api/translate` - ترجمه همزمان
- `POST /api/translate/form` - ترجمه از فرم
- `POST /api/translate/heavy` - ترجمه سنگین در پس‌زمینه
- `POST /api/translate/session` - ترجمه با session

### 📊 پیگیری وضعیت
- `GET /api/progress/{session_id}` - پیشرفت ترجمه
- `GET /api/status/{session_id}` - وضعیت session
- `POST /api/check-completion` - بررسی تکمیل
- `POST /api/check-translation-status` - وضعیت ترجمه

### 🌐 زبان‌ها و آمار
- `GET /api/languages` - لیست زبان‌های پشتیبانی شده
- `GET /api/stats` - آمار کلی
- `GET /api/cache/stats` - آمار کش

### ⚙️ مدیریت
- `POST /api/cache/clear` - پاک کردن کش
- `POST /api/webhook/wordpress` - Webhook وردپرس
- `POST /api/check-auto-charge-status` - وضعیت کسر اعتبار

## 📝 نحوه استفاده

### ترجمه ساده
```python
import requests

url = "https://your-space-url/api/translate"
data = {
    "text": "Hello, how are you?",
    "source_lang": "English",
    "target_lang": "Persian"
}

response = requests.post(url, json=data)
result = response.json()
print(result["translated_text"])
```

### ترجمه با پیگیری پیشرفت
```python
# شروع ترجمه با session
response = requests.post("https://your-space-url/api/translate/session", json={
    "text": "متن طولانی برای ترجمه...",
    "source_lang": "Persian",
    "target_lang": "English"
})

session_id = response.json()["session_id"]

# پیگیری پیشرفت
progress_response = requests.get(f"https://your-space-url/api/progress/{session_id}")
progress = progress_response.json()
print(f"پیشرفت: {progress['progress']}%")
```

### ترجمه پس‌زمینه
```python
# شروع ترجمه سنگین
response = requests.post("https://your-space-url/api/translate/heavy", json={
    "text": "متن بسیار طولانی...",
    "source_lang": "English",
    "target_lang": "Persian",
    "auto_charge": True
})

request_id = response.json()["request_id"]

# بررسی وضعیت
status_response = requests.post("https://your-space-url/api/check-translation-status", json={
    "request_id": request_id
})
```

## 🌍 زبان‌های پشتیبانی شده

سرویس از بیش از 100 زبان پشتیبانی می‌کند از جمله:

**اروپایی**: انگلیسی، اسپانیایی، فرانسوی، آلمانی، ایتالیایی، پرتغالی، روسی، لهستانی، چکی، مجارستانی، رومانیایی، یونانی، هلندی، سوئدی، نروژی، دانمارکی، فنلاندی

**آسیایی**: فارسی، عربی، چینی، ژاپنی، کره‌ای، هندی، تایلندی، ویتنامی، اندونزیایی، مالایی، تامیل، بنگالی، اردو

**آفریقایی**: سواحیلی، امهری، یوروبا، ایگبو، هوسا، سومالی، آفریکانس، زولو، خوسا

و بسیاری زبان‌های دیگر...

## ⚡ عملکرد

- **سرعت**: ترجمه متون کوتاه در کمتر از 2 ثانیه
- **کش**: استفاده مجدد از ترجمه‌های قبلی
- **موازی‌سازی**: پردازش همزمان چندین درخواست
- **GPU**: استفاده خودکار از GPU در صورت وجود

## 🔧 پیکربندی

### متغیرهای محیطی
```bash
PORT=7860                           # پورت سرویس
WORDPRESS_NOTIFICATION_URL=...      # URL اطلاع‌رسانی WordPress
MODEL_CACHE_DIR=./models           # مسیر ذخیره مدل
```

### تنظیمات داخلی
```python
MODEL_NAME = "facebook/m2m100_418M"  # مدل M2M100
CACHE_EXPIRY = 3600                  # مدت انقضا کش (ثانیه)
MAX_CHUNK_SIZE = 350                 # حداکثر اندازه بخش
MAX_WORKERS = 3                      # تعداد worker
```

## 🛠️ توسعه

### ساختار پروژه
```
├── app.py              # فایل اصلی
├── requirements.txt    # وابستگی‌ها
├── Dockerfile         # تنظیمات Docker
├── README.md          # مستندات
└── models/            # مدل‌های ذخیره شده
```

### کلاس‌های اصلی
- `MultilingualTranslator`: مدیریت ترجمه
- `TranslationCache`: کش نتایج
- `TextChunker`: تقسیم متن
- `TranslationQueue`: صف وظایف

## 🤝 مشارکت

1. Fork کنید
2. شاخه جدید بسازید (`git checkout -b feature/amazing-feature`)
3. تغییرات را commit کنید (`git commit -m 'Add amazing feature'`)
4. Push کنید (`git push origin feature/amazing-feature`)
5. Pull Request بسازید

## 📄 لایسنس

این پروژه تحت لایسنس MIT منتشر شده است.

## 🙏 تشکر

- [Facebook M2M100](https://github.com/pytorch/fairseq/tree/master/examples/m2m_100) برای مدل ترجمه
- [Hugging Face Transformers](https://huggingface.co/transformers/) برای کتابخانه
- [FastAPI](https://fastapi.tiangolo.com/) برای فریمورک وب

## 📞 پشتیبانی

برای گزارش مشکلات یا درخواست ویژگی جدید، لطفاً یک Issue ایجاد کنید.

---

**ساخته شده با ❤️ برای جامعه متن‌باز**