Tashkeel

---
name: tashkeel
description: Arabic diacritization (tashkeel) via Farasa API, pyarabic, and LLM fallback
version: 1.0.0
author: Mousa Abu Mazin
license: MIT
platforms: [linux, macos]
prerequisites:
  commands: [curl, python3]
  env_vars: []
metadata:
  hermes:
    tags: [language, diacritization, tashkeel, arabic]
---
# التشكيل العربي

أداة لتشكيل النصوص العربية بالحركات (فتحة، ضمة، كسرة، سكون، شدة، تنوين). التشكيل مهم للنطق الصحيح، خصوصاً في النصوص القرآنية والشعرية والتعليمية. يدعم عدة طرق: واجهة Farasa البرمجية من QCRI، مكتبة pyarabic المحلية، أو الاعتماد على نموذج اللغة الكبير مباشرة كحل أخير.

## متى تستخدم
- المستخدم يطلب تشكيل نص عربي
- يريد نطق صحيح لكلمة أو جملة
- نص قرآني أو شعري يحتاج تشكيل
- يريد تحسين نطق TTS بإضافة الحركات

## الطريقة الأولى: Farasa API من QCRI (الأساسية)

```bash
curl -s -X POST "https://farasa-api.qcri.org/diacritize" \
  -H "Content-Type: application/json" \
  -d '{"text": "ذهب الولد الى المدرسة"}'
```

النتيجة المتوقعة:
```
ذَهَبَ الوَلَدُ إِلَى المَدْرَسَةِ
```

## الطريقة الثانية: pyarabic (محلي — بدون إنترنت)

```bash
pip install pyarabic
```

```python
import pyarabic.araby as araby

text = "بسم الله الرحمن الرحيم"

# التحقق من وجود تشكيل
print(araby.is_vocalized(text))  # False

# إزالة التشكيل (مفيد للمقارنة)
vocalized = "بِسْمِ اللَّهِ الرَّحْمَنِ الرَّحِيمِ"
print(araby.strip_tashkeel(vocalized))  # بسم الله الرحمن الرحيم
```

> **ملاحظة**: pyarabic يوفر أدوات للتعامل مع التشكيل (فحص، إزالة، تحليل) لكنه لا يولّد تشكيلاً كاملاً تلقائياً. للتشكيل التلقائي استخدم Farasa أو نموذج اللغة.

## الطريقة الثالثة: نموذج اللغة الكبير (احتياطي)

إذا كانت واجهة Farasa غير متاحة و pyarabic لا يكفي، يمكن الاعتماد على نموذج اللغة الكبير مباشرة:

```
"شكّل النص التالي بالحركات العربية الكاملة: ذهب الولد الى المدرسة"
```

النموذج يستطيع تشكيل النصوص بدقة جيدة خصوصاً للنصوص الفصحى المعروفة.

## أمثلة إدخال وإخراج

| الإدخال (بدون تشكيل) | الإخراج (مع تشكيل) |
|----------------------|---------------------|
| كتب الطالب الدرس | كَتَبَ الطَّالِبُ الدَّرْسَ |
| ذهب الولد الى المدرسة | ذَهَبَ الوَلَدُ إِلَى المَدْرَسَةِ |
| بسم الله الرحمن الرحيم | بِسْمِ اللَّهِ الرَّحْمَنِ الرَّحِيمِ |
| العلم نور | العِلْمُ نُورٌ |

## الحركات الأساسية
| الحركة | الرمز | المثال |
|--------|-------|--------|
| فتحة | َ | كَتَبَ |
| ضمة | ُ | كُتُبٌ |
| كسرة | ِ | بِسْمِ |
| سكون | ْ | مِنْ |
| شدة | ّ | محمَّد |
| تنوين فتح | ً | كتاباً |
| تنوين ضم | ٌ | كتابٌ |
| تنوين كسر | ٍ | كتابٍ |

## القواعد
- لا تشكّل نص بلهجة عامية — التشكيل للفصحى فقط
- إذا النص قرآني، تأكد من التشكيل بالرجوع للمصحف
- إذا كلمة تحتمل أكثر من تشكيل، اذكر الاحتمالات مع المعنى
- جرّب Farasa أولاً، ثم pyarabic للتحليل، ثم نموذج اللغة كاحتياطي