Quran Words - قاعدة بيانات كلمات القرآن الكريم

قاعدة بيانات احترافية ومتكاملة لجميع كلمات القرآن الكريم — من النص العثماني إلى التحليل الصرفي الدقيق، مروراً بالجذور والمصادر والمشتقات والمعاني من المعاجم الكلاسيكية.

الهدف: أن تكتب SELECT واحداً لتحصل على الكلمة + جذرها + مصدرها + كل مشتقاتها + معناها من لسان العرب.

📦 حجم المستودع: الكود ~4.6 MB (حسب GitHub API size: 4704 KB) + البيانات عبر Git LFS ~415 MB ( quran_words.db 114 MB + arabic_roots.json 169 MB + arabic_roots.parquet 83 MB + quranic_corpus_morphology.json 43 MB + quranic-corpus-morphology-0.4.txt 6.2 MB). بعد git clone --depth 1 ستحتاج git lfs pull لسحب ملفات data/ كاملة. كامل المشروع على القرص بعد التثبيت ~1.7 GB (مع .git/lfs و node_modules و .venv).

• إحصائيات
• لقطات الشاشة
• ما الجديد؟
• هيكل المشروع
• المتطلبات
• الاستنساخ السريع
• البدء السريع بدون بناء
• تشغيل الخلفية Django
• تشغيل الواجهة Next.js
• التشغيل المتكامل
• بناء القاعدة من الصفر
• هيكل قاعدة البيانات
• واجهة البرمجة API
• أمثلة على الاستعلامات
• مصادر البيانات والتراخيص
• لماذا CAMeL وليس Farasa؟
• استكشاف الأخطاء
• المساهمة والترخيص

quran-words/
├── README.md
├── LICENSE
├── .gitattributes
├── data/
│   ├── quran_words.db
│   ├── quranic_corpus_morphology.json
│   ├── quranic-corpus-morphology-0.4.txt
│   ├── arabic_roots.json
│   └── arabic_roots.parquet
├── backend/
│   ├── manage.py
│   ├── requirements.txt
│   ├── config/
│   ├── core/
│   ├── quran/
│   ├── words/
│   ├── morphology/
│   ├── roots/
│   ├── derivatives/
│   ├── sources/
│   ├── search/
│   ├── .venv/
│   └── scripts/smoke_api.py
├── frontend/
│   ├── package.json
│   ├── vendor/next-16.3.2.tgz
│   ├── .npmrc
│   ├── next.config.ts
│   ├── src/
│   │   ├── app/
│   │   │   ├── page.tsx
│   │   │   ├── search/page.tsx
│   │   │   ├── roots/[root]/page.tsx
│   │   │   ├── words/[id]/page.tsx
│   │   │   ├── surahs/[id]/page.tsx
│   │   │   ├── guide/morphology/
│   │   │   └── sources/page.tsx
│   │   ├── components/
│   │   └── lib/
│   │       ├── api.ts
│   │       └── normalize.ts
│   └── public/
├── scripts/
│   ├── download_quran.py
│   ├── fetch_corpus.py
│   ├── fetch_arabic_roots.py
│   ├── build_db.py
│   ├── build_morphology.py
│   ├── build_masadir_derivatives.py
│   ├── build_root_glosses.py
│   └── build_plain_columns.py
└── examples/
    ├── queries.sql
    └── masadir_queries.sql

تحقق سريع:

python3 --version  # فحص بايثون
node --version  # فحص نود
npm --version  # فحص npm
git lfs version  # فحص LFS

مهم: استخدم --depth 1 لتجنب تحميل كامل السجل (يوفّر ~800 MB من .git history). البيانات الكبيرة تُسحب عبر Git LFS.

git clone --depth 1 https://github.com/AhmedSaadi0/quran-words.git  # استنساخ سريع
cd quran-words  # دخول المشروع

git lfs pull  # سحب البيانات

ls -lh data/quran_words.db  # تحقق DB
ls -lh data/arabic_roots.json  # تحقق المعجم

بدون Git LFS سترى ملفات pointer صغيرة (134 byte). إن حدث ذلك شغّل git lfs install && git lfs pull.

لتحديث لاحقاً بعد --depth 1:

git pull --depth 1  # تحديث سريع
git lfs pull  # سحب البيانات

استخدم القاعدة الجاهزة مباشرة (لا حاجة لإعادة البناء):

sqlite3 data/quran_words.db  # فتح القاعدة
sqlite> SELECT * FROM masadir WHERE root='كتب' LIMIT 5;  # مثال مصادر
sqlite> SELECT * FROM derivatives WHERE root='علم' AND is_quranic=1;  # مثال مشتقات
sqlite> .quit  # خروج

python3 -c "
import sqlite3  # استيراد
conn = sqlite3.connect('data/quran_words.db')  # اتصال
print(conn.execute(\"SELECT masdar_plain FROM masadir WHERE root='رحم' LIMIT 3\").fetchall())  # استعلام سريع
"

import sqlite3  # استيراد
conn = sqlite3.connect("data/quran_words.db")  # اتصال
conn.execute("SELECT masdar_plain FROM masadir WHERE root='رحم'").fetchall()  # استعلام

الخلفية تقرأ data/quran_words.db مباشرة كـ managed=False (لا إعادة إنشاء) عبر backend/config/settings.py:64.

python3 -m venv backend/.venv  # إنشاء البيئة

source backend/.venv/bin/activate  # تفعيل البيئة

pip install --upgrade pip  # ترقية pip
pip install -r backend/requirements.txt  # تثبيت المتطلبات

python backend/manage.py migrate --run-syncdb  # تهيئة الجداول

backend/config/settings.py:64 يشير إلى BASE_DIR.parent / "data" / "quran_words.db" مع timeout: 20. CORS_ALLOW_ALL_ORIGINS = True و ALLOWED_HOSTS = ["*"] للتطوير (قيّده في الإنتاج).

python backend/manage.py runserver 0.0.0.0:8000 --noreload  # تشغيل الخادم

افتح في المتصفح أو عبر curl:

curl http://127.0.0.1:8000/api/stats/ | jq  # إحصائيات

curl "http://127.0.0.1:8000/api/search/?q=%D9%83%D8%AA%D8%A8" | jq  # بحث
curl "http://127.0.0.1:8000/api/masadir/?root=%D9%83%D8%AA%D8%A8" | jq  # مصادر
curl "http://127.0.0.1:8000/api/words/1/detail/" | jq  # تفاصيل كلمة

المتصفح: http://127.0.0.1:8000/api/ — واجهة DRF القابلة للتصفح.

pip install gunicorn  # تثبيت gunicorn
gunicorn config.wsgi:application --bind 0.0.0.0:8000 --workers 3 --timeout 60  # تشغيل إنتاجي
backend/.venv/bin/gunicorn config.wsgi:application --chdir backend --bind 0.0.0.0:8000  # إنتاج من الجذر

backend/.venv/bin/python backend/scripts/smoke_api.py --base http://127.0.0.1:8000/api  # اختبار API

backend/.venv/bin/python backend/scripts/smoke_api.py --base http://127.0.0.1:8765/api \  # اختبار مقارنة
    --save /tmp/opencode/after --compare /tmp/opencode/baseline

ملاحظة جانغو 6.1: يتطلب Python 3.13 في البيئة الحالية (IMPLEMENTATION_PLAN.md). إن كنت على 3.11/3.12 ثبّت Django 5.x أو حدّث بايثون.

الواجهة مبنية بـ Next.js 16 + Tailwind 4 + RTL كامل + خط Amiri (frontend/src/app/layout.tsx).

cd frontend  # دخول الواجهة

npm install  # تثبيت الحزم

ls node_modules/.bin/next  # تحقق التثبيت

ملاحظة vendor/: مجلد frontend/vendor/ يحوي next-16.3.2.tgz و swc و sharp tarballs لتجاوز الشبكة البطيئة. على شبكة جيدة يمكنك حذف vendor/ وإرجاع "next": "16.3.2" في package.json.

الواجهة تتصل بالخلفية عبر frontend/src/lib/api.ts:6:

export const API_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:8000/api";

echo 'NEXT_PUBLIC_API_URL=http://localhost:8000/api' > .env.local  # إعداد محلي
echo 'NEXT_PUBLIC_API_URL=https://api.example.com/api' > .env.local  # إعداد إنتاجي

npm run dev  # تشغيل مطور

افتح http://localhost:3000 — يجب أن ترى:

• شريط بحث كبير (ابحث بجذر: كتب / بمصدر: كتابة / بكلمة: عَلِيم)
• 6 بطاقات إحصائيات من /api/stats/
• شبكة جذور (20/صفحة)

npm run build  # بناء الإنتاج
npm start  # تشغيل الإنتاج
npm run lint  # فحص الكود

ملاحظة Next 16: params و searchParams هما Promise → await props.params في page.tsx.

تحتاج نافذتين (terminal):

source backend/.venv/bin/activate  # تفعيل البيئة
python backend/manage.py runserver 0.0.0.0:8000 --noreload  # تشغيل الخادم

cd frontend  # دخول الواجهة
npm run dev  # تشغيل مطور

تجربة سريعة متكاملة:

1. افتح http://localhost:3000
2. ابحث عن كتب → سترى جذور/مصادر/كلمات من GET /api/search/?q=كتب
3. ادخل صفحة جذر /roots/كتب → تبويبات المعاني/المصادر/المشتقات
4. ادخل صفحة كلمة /words/1 → تحليل صرفي + كل مواضعها
5. ادخل صفحة سورة /surahs/1 → عرض مصحفي مع hover للتحليل

إن فشل الاتصال، تأكد أن NEXT_PUBLIC_API_URL يشير إلى المنفذ الصحيح وأن الباكند يعمل على 8000.

تخطَّ هذا القسم إن كنت تستخدم data/quran_words.db الجاهزة (114 MB). للبناء الكامل تحتاج ~50 MB إضافية لـ CAMeL + ~250 MB بيانات خام.

python --version  # فحص بايثون
pip install --user camel-tools pyarrow  # تثبيت CAMeL
camel_data -i morphology-db-msa-r13  # تحميل CAMeL

python scripts/download_quran.py  # تحميل القرآن
python scripts/fetch_corpus.py  # جلب QAC
python scripts/fetch_arabic_roots.py  # جلب الجذور

python scripts/build_db.py  # بناء أساسي
python scripts/build_morphology.py  # بناء صرفي

python scripts/build_masadir_derivatives.py  # بناء مصادر

python scripts/build_root_glosses.py  # بناء ملخص
python scripts/build_plain_columns.py  # أعمدة مبسطة

ملاحظة الحجم: camel-tools نفسها 0.12MB لكنها تتطلب scikit-learn/camel-kenlm (~12MB) + قاعدة calima-msa-r13 (~40MB). torch (526MB) مطلوب فقط لنموذج BERT السياقي وغير لازم لهذا السكربت.

Git LFS: بعد البناء، الملفات الكبيرة (*.db, *.parquet) تُتعقّب عبر data/** filter=lfs في .gitattributes. لا تُحمّلها مباشرة في git بدون LFS.

الخلفية تكشف 15 endpoint عبر backend/config/urls.py:4 → api/ (انظر backend/README.md للتفصيل الكامل).

المعنى السريع: كل استجابات الجذور (قائمة/تفصيل/بحث) وكائن root في تفاصيل الكلمة تتضمن gloss_ar/gloss_en/gloss_source — مختصراً من جدول root_glosses (يُبنى بـ python scripts/build_root_glosses.py).

تطبيع البحث: backend/core/utils.py:strip_diacritics + normalize_ar يطبّع ٱلرَّحْمـٰنِ ↔ الرحمن في الخلفية والواجهة (frontend/src/lib/normalize.ts نسخة JS مطابقة).

curl "http://127.0.0.1:8000/api/search/?q=%D9%83%D8%AA%D8%A8" | jq  # بحث
curl "http://127.0.0.1:8000/api/masadir/?root=%D9%83%D8%AA%D8%A8" | jq  # مصادر
curl "http://127.0.0.1:8000/api/words/1/detail/" | jq  # تفاصيل كلمة
curl "http://127.0.0.1:8000/api/surahs/1" | jq  # سورة
curl "http://127.0.0.1:8000/api/ayah-words/?surah=1&page_size=2" | jq  # آيات مع كلمات

انظر backend/README.md:88-100 لهيكلة الـ Apps الثمانية.

SELECT a.ayah, wa.position, w.text, wm.pos, r.root, wm.form  -- فاتحة مع تحليل
FROM word_ayah wa
JOIN words w ON wa.word_id=w.id
JOIN ayat a ON wa.ayah_id=a.id
LEFT JOIN word_morphology wm ON wm.word_ayah_id=wa.id
LEFT JOIN roots r ON r.id=wm.root_id
WHERE a.surah=1 ORDER BY a.ayah, wa.position;

SELECT rm.book_name, rm.definition FROM roots r  -- معنى جذر
JOIN root_meanings rm ON rm.root_id=r.id WHERE r.root='رحم' LIMIT 3;

SELECT masdar_ar, pattern, form, is_attested, source  -- مصادر كتب
FROM masadir WHERE root='كتب' ORDER BY is_attested DESC, confidence DESC;

SELECT form_ar, derivative_type, pattern FROM derivatives  -- مشتقات علم
WHERE root='علم' AND is_quranic=1;

SELECT w.text, r.root, m.masdar_plain, m.pattern  -- كلمات مع مصادر
FROM word_ayah wa
JOIN words w ON wa.word_id=w.id
JOIN word_morphology wm ON wm.word_ayah_id=wa.id
JOIN roots r ON r.id=wm.root_id
JOIN masadir m ON m.root_id=r.id
WHERE wa.ayah_id=1 GROUP BY wa.id LIMIT 5;

SELECT DISTINCT a.surah, a.ayah, a.text_uthmani  -- آيات بمصدر رحمة
FROM masadir m
JOIN word_masdar wmd ON wmd.masdar_id=m.id
JOIN word_ayah wa ON wa.id=wmd.word_ayah_id
JOIN ayat a ON a.id=wa.ayah_id
WHERE m.masdar_plain='رحمة' LIMIT 5;

المزيد في examples/queries.sql و examples/masadir_queries.sql.

تنبيه GPL: المتن النحوي ومعاني الجذور GPL؛ عند التوزيع يجب ذكر المصدر والرابط (جدول sources) وتوفير الكود المصدري للتعديلات.

تم الاحتفاظ بـ QAC كـ ground truth وعدم استبدال جذوره بأي محلل آلي.

مرحباً بالمساهمات:

• إضافة ترجمات بلغات أخرى
• تحسين قوائم الأوزان (MASDAR_PATTERNS_BY_FORM في build_masadir_derivatives.py)
• إضافة معاجم جديدة
• إصلاح التشكيل للمصادر
• تحسين واجهة Next.js (مكونات src/components/)

git clone --depth 1 https://github.com/AhmedSaadi0/quran-words.git  # استنساخ سريع
cd quran-words  # دخول المشروع

كود المشروع: MIT (LICENSE). البيانات: انظر الجدول أعلاه (CC-BY-4.0 / GPL / GPL-3.0 / MIT).

Quran.com و Quranic Arabic Corpus و Hawramani و CAMeL Lab - NYU Abu Dhabi على البيانات المفتوحة.