التسمية

لكل مفهوم اسم واحد مشتق من العربية، وهذه قواعد تسمية الجداول والحقول والمسارات والحزم التي تتضمن مفاهيم قرآنية.

القاعدة الأساسية: لكل مفهوم قرآني اسم معتمد واحد نستخدمه في النموذج والجدول والمفتاح الأجنبي وواجهة API، ونبحث عنه في القاموس بدل ابتكار اسم في أثناء كتابة الكود.

تجمع هذه الصفحة ما يحتاجه المطور، أما معيار المصطلحات الكامل فيشرح طريقة اشتقاق الاسم من صيغته العربية بالحركات وطريقة كتابة مدخل في القاموس، ولا تحتاج إليه إلا عند إضافة مفهوم إلى القاموس.

1. استخدم اسمًا واحدًا لكل مفهوم

حدد المفهوم ثم ابحث عن اسمه.

1.1 حدد المفهوم وما لا يشمله قبل أن تسميه.

بدل أن نسأل:  كيف نترجم هذه الكلمة؟
نسأل:         ما المفهوم الذي نمثله، وكيف يختلف عن المفاهيم القريبة منه؟

يفحصه: حقلا definition وboundaries المطلوبان في كل مدخل في القاموس، ويفحصهما tools/validate.py.

1.2 لكل مفهوم اسم code معتمد واحد، ولا يشترك مفهومان في اسم واحد.

surah   ayah   word   mushaf   tajwid

يلزم توحيد تهجئة الاسم بين المستودعات المرتبطة أيضًا؛ فإذا كتبت حزمة hafs-kfgqpc في ملف manifest وhafs-kfqc في صفحاتها، أو كتب فهرس qalon وdouri وsousi بينما يستخدم dataset النصي qalun وduri وsusi، احتاج كل مشروع يستخدم هذه البيانات إلى جدول يربط التهجئات ببعضها.

يفحصه: يوقف tools/build_aliases.py البناء إذا اشترك مدخلان في اسم واحد بأي تهجئة مسجلة لهما.

1.3 ابحث عن الاسم في القاموس قبل أن تكتبه، لأن أكثر الأسماء «الجديدة» تهجئات لمداخل موجودة.

python3 skills/quranic-terminology/scripts/lookup.py aya verse "Waqf Lazim" مصحف
python3 skills/quranic-terminology/scripts/lookup.py --search waqf

يفحصه: يبلغ audit_terminology.py --strict عن التهجئة غير المعتمدة ويذكر المدخل الذي تنتمي إليه.

1.4 اقترح إضافة المفهوم غير الموجود في القاموس قبل دمج الكود الذي يحتاج إليه.

يمكن للمشروع الاحتفاظ بمفاهيمه الخاصة في مجلد مفاهيم بجانب مجلد المعيار، إذا كان تعريفها لا يستند إلى القرآن أو المصحف (المعيار، القسم 30).

يفحصه: نموذج اقتراح المصطلح ووضع --strict في أداة الفحص، الذي يكشف الأسماء القرآنية غير الموجودة في القاموس.

2. العربية أو الإنجليزية

يحتفظ المفهوم القرآني أو المتخصص في العلوم الشرعية باسمه العربي، ونستخدم الاسم الإنجليزي للمفهوم العام.

2.1 احتفظ بالمصطلح العربي إذا دل على مفهوم قرآني أو متخصص في العلوم الشرعية، واستخدم الإنجليزية البسيطة للمفهوم العام.

العربية:      surah  ayah  mushaf  juz  hizb  qiraah  riwayah  tajwid  tafsir
الإنجليزية:   word  letter  page  line  root  translation  glyph

surah → ayah → word       وليس  chapter → verse → word
                         وليس  surah → ayah → kalimah

يفحصه: يبلغ audit_terminology.py عن المقابل الإنجليزي مثل verse أو chapter حين يحل محل الاسم القرآني، ويشير إلى المدخل.

2.2 في الاسم المركب، انقل الكلمة الاصطلاحية بحروف لاتينية وترجم الكلمة العامة، وفق ترتيب الكلمات في الإنجليزية.

المِيم الصَّغِيرَة      → small_meem        وليس meem_saghirah
عَلَامَة الوَقْف        → waqf_mark
نَوْع عَلَامَة الوَقْف   → waqf_mark_type
النُّون السَّاكِنَة     → noon_sakinah      تبقى «ساكنة» لأنها مصطلح تجويدي

يفحصه: يشتق tools/check_conformance.py كل اسم مركب من أصله العربي بالحركات ومن قائمة الكلمات العامة في general_words.tsv.

2.3 اشتق التهجئة البرمجية للمصطلح من صيغته العربية بالحركات باستخدام دالة واحدة، ولا تخترها حسب ذوقك.

python3 tools/translit.py "رُبْع الحِزْب"     # rub_al_hizb

قواعد الاشتقاق في الأقسام 4–8 من المعيار، وتحتاج إليها فقط عند إضافة اسم، أما استخدام اسم موجود فلا يتطلب معرفتها.

يفحصه: يحتوي tools/test_translit.py على الحالات المرجعية، ويتحقق tools/check_conformance.py من أن code في كل مدخل يطابق الاسم المشتق من صيغته العربية.

3. الاسم البرمجي واسم العرض

المعرف واسم العرض حقلان منفصلان، وقد يختلفان.

3.1 يحتوي code على المعرف المستخدم في الكود وواجهات API وقواعد البيانات، ويحتوي display على الاسم المعروض للقارئ، وقد يختلف الاسمان وهذا مقصود.

code:     tajwid          qiraah
display:  Tajweed         Qiraah

يفحصه: يحدد tools/measure_display.py التهجئة الإنجليزية الأكثر شيوعًا بالقياس، وتُسجل النتيجة في حقل display_evidence في المدخل قبل اعتمادها.

3.2 اكتب المفهوم في الشرح بتهجئة code وبحروف صغيرة، واترك display للواجهات.

نعم:  The mushaf carries tajwid colouring on every ayah.
لا:   The Mushaf carries Tajweed colouring on every Ayah.

تخص القاعدة النصوص التوضيحية في المستودع وملف README وأدلته وهذه الصفحات. أما واجهة المستخدم، بما فيها موقع التوثيق، فهي موضع لعرض الأسماء ويجوز أن تستخدم صيغة display وفق القاعدة 5.4، على أن تأخذها من المدخل دون الاحتفاظ بقائمة أخرى خاصة بها.

يفحصه: يربط tools/check_examples.py كل اسم مكتوب في صفحات المستودع بمدخله.

3.3 للتهجئة البديلة والمقابل الإنجليزي والاسم المهجور 3 حقول منفصلة، ولا يحل أي منها محل الاسم المعتمد.

ayah:   alternative_spellings: aya, ayat     english_glosses: Verse

يفحصه: يرفض tools/check_conformance.py تسجيل المقابل الإنجليزي أيضًا بوصفه تهجئة بديلة، ويبين lookup.py نوع الاسم الذي طابق القيمة المدخلة.

3.4 الاسم المهجور اسم حل غيره محله وليس اسمًا خاطئًا، ويبقى مرتبطًا بمدخله حتى يمكن فحص الكود القديم.

يفحصه: يربط lookup.py الاسم المهجور بمدخله ويبين أنه مهجور، ويبلغ عنه audit_terminology.py مع الاسم الذي حل محله.

4. شكل الاسم

الاسم كامل ودقيق ودون اختصار.

4.1 استخدم الاسم كاملًا دون اختصار، ولا تستخدم كلمة مبهمة حين يوجد اسم دقيق.

نعم:  surah  ayah  word  translation
لا:   srh  ay  wrd  trans  data  info  item  value

يفحصه: يبلغ audit_terminology.py --strict عن الاختصارات والأسماء المبهمة.

4.2 أضف s إلى الاسم البرمجي كاملًا لصياغة الجمع، ولا تستخدم الجمع العربي اسمًا للمجموعة.

نعم:  ayahs  surahs  juzs  hizbs  riwayahs
لا:   ayat  suwar  ajza  ahzab

يفحصه: يفحص tools/check_conformance.py كل جمع مسجل، ويبلغ الفحص عن الجمع العربي المستخدم اسمًا للمجموعة.

4.3 يحتوي id على المفتاح الداخلي، وnumber على الرقم الذي يستخدمه القارئ للإشارة إلى العنصر، وposition على موضعه في تسلسل، وorder على ترتيبه بحسب المعنى.

ayah_id   surah_number   word_position   revelation_order

وجد المسح word_index وword_number وsegment_number في جدول واحد، ولم يتبين من الأسماء هل يبدأ word_index من 0.

يفحصه: يكشف الفحص استخدام اللاحقتين index وidx، أما اختيار اللاحقة المناسبة من اللواحق الـ4 فيلتزم فيه الكاتب بقاعدة المعيار (القسم 21).

4.4 سمِّ التصنيف باسم ما يصنفه، ولا تسمه type.

waqf_ruling        وليس waqf_type
recitation_style   وليس recitation_type
waqf_mark_type     الاستثناء الوحيد: نوع العلامة المرسومة

يفحصه: يبلغ الفحص عن اللاحقة type على مفهوم قرآني (المعيار، القسم 24).

4.5 خزّن في عمود التصنيف قيم code لأعضاء السجل، ولا تخزن أسماء العرض بأي من اللغتين.

نعم:  revelation_classification = "makki" | "madani" | "disputed"
لا:   enum('meccan', 'medinan')     surah_type: "مدنية"

يفحصه: فحص للمخطط يتأكد من أن كل قيمة في عمود التصنيف موجودة في سجله.

5. وحّد الاسم في جميع الطبقات

نستخدم الأسماء نفسها في النموذج والجدول والمفتاح الأجنبي والمسار والحزمة.

5.1 استخدم الاسم نفسه للنموذج والجدول والمفتاح الأجنبي ومسار API، مع اختلاف صيغته في المواضع الـ4.

النموذج:         Ayah            Riwayah
الجدول:          ayahs           riwayahs
المفتاح الأجنبي:  ayah_id         riwayah_id
API:             /ayahs          /riwayahs

وجد المسح مفهومًا واحدًا له 3 صيغ للاسم: تهجئة مختصرة في النموذج، والتهجئة نفسها مع s في اسم الجدول، والجمع العربي في المسار.

يفحصه: تشغيل audit_terminology.py --strict على جميع ملفات المستودع مع كل طلب دمج.

5.2 سمِّ المستودع أو الحزمة باسم code من القاموس بصيغة kebab-case، واستخدم صيغة snake_case لكل الأسماء داخله.

المستودع:  qiraat-ayah-map   mushaf-layout   ayah-timing
داخله:     ayah_numbering_system   mushaf_edition

يفحصه: تشغيل الفحص مع تضمين اسم المستودع.

5.3 انقل الأسماء التي يحددها طرف آخر كما يكتبها صاحبها تمامًا، مثل اسم عمود لدى المورد أو اسم عائلة خط أو اسم محرف في Unicode.

يفحصه: قائمة external_names في .terminology.json، ويستثني الفحص الأسماء المدرجة فيها.

5.4 يجوز لواجهة المستخدم أن تترجم الاسم أو تعرضه بصورة مختلفة، أما الطبقات الـ4 فتلتزم بالاسم نفسه.

يفحصه: قائمة allow_gloss_in في .terminology.json التي تسمح بالمقابل الإنجليزي في نصوص الواجهة وحدها.

6. تشغيل الفحص

الفحص يبلغ عن المخالفات، ولا يعيد تسمية شيء.

6.1 يشغّل كل مستودع يتضمن مفاهيم قرآنية فحص المصطلحات في CI ويمنع الدمج عند وجود خطأ.

python3 skills/quranic-terminology/scripts/audit_terminology.py src --strict

يفحصه: سير عمل CI في المستودع ورمز الخروج من الفحص.

6.2 سجّل معلومات المشروع التي يحتاجها الفحص في .terminology.json، واستخدم تعليقًا يتضمن terminology: ignore لاستثناء سطر واحد.

paths            ما يفحصه عند عدم تحديد مسار
exclude          مجلدات تشترك مع القرآن في كلمة لكنها تتناول موضوعًا آخر
ignore_words     كلمات لها معنى آخر في هذا المشروع
allow_gloss_in   API المنشورة ونصوص الواجهة
external_names   أسماء منقولة من مورد أو خط أو Unicode
compatibility    أعمدة وصيغ تبادل تحتاج إعادة تسميتها إلى ترحيل، ويبلغ عنها مرة واحدة

يفحصه: يوثق skills/quranic-terminology/assets/terminology.example.json كل مفتاح، ويرفض الفحص أي مفتاح غير معروف.

المصدر: quran-ws/docs، عند d1d6be33be9d. ما لم يُوسم «معتمد» فهو مقترح للنقاش، ولا يُبنى عليه بعد.