الميزات العربية والثقافية

كاظمه عربية الأصل: العربية تعمل مباشرة، إلى جانب الإنجليزية. يغطي هذا المستند المكوّنات التي تنفّذ ذلك: كشف اللهجة والمُقطِّعات، والعربية في البحث، وطبقة التدويل + واجهة RTL، وبروتوكول المجلس الثقافي — كلها مرجعية المصدر، مع ملاحظات صادقة عن النطاق. وللهندسة التي تحتها (الاتجاه، وتشكيل الحروف، وطيّ البحث، والذاكرة العربية، وقراءة PDF والتعرف الضوئي)، راجع كيف تتعامل كاظمه مع العربية.

---

1. المكوّنات

المكوّن	الحزمة	الدور
كشف اللهجة + المُقطِّعات	kazma-core ‏(dialect_detector.py، tokenizer.py)	تمييز الكويتية من الفصحى وتقطيع كلٍّ منهما، لموجِّه اللهجات.
العربية في البحث والمستندات	kazma-core ‏(documents/arabic.py)	صيغة موحّدة واحدة لفهرسة العربية والبحث فيها؛ والموطن الوحيد لسياسة النص العربي في قراءة المستندات وكتابتها.
واجهة التدويل + RTL	kazma-ui	ترجمة سلاسل الواجهة، وضبط dir/lang لكل طلب، وسياسة الخطوط.
بروتوكول المجلس	kazma-core	التحية والوداع الخليجيان على مسار تطبيقات الدردشة.

هذه طبقات مستقلة. لا تعتمد المُقطِّعات على نظام التدويل، والمجلس وحدة محادثة أساسية — لا ميزة واجهة.

---

2. كشف اللهجة والمُقطِّعات

يكشف kazma-core/kazma_core/tokenizer.py ‏(DualEngineTokenizer) اللهجة أولًا — يميّز dialect_detector.py بين الكويتية والمصرية والشامية والمغاربية والفصحى، بـ fasttext حين يكون مثبّتًا وبالقواعد في غير ذلك، والعلامات الكويتية مأخوذة من arabic/kuwaiti_lexicon.py — ثم يسلّم النص الكويتي إلى KuwaitiTokenizer ‏(kuwaiti_tokenizer.py: كلمات اللهجة تبقى كما هي، والتبديل بين العربية والإنجليزية، وأسماء العلم) وكل ما عداه إلى MSATokenizer ‏(msa_tokenizer.py). وموجِّه اللهجات (kazma_core/router.py، الذي يستخدمه محرك التوجيه) هو من يستدعيه.

يطبّع MSATokenizer في خطوتين:

1. إزالة التشكيل — علامات التشكيل (\u064B–\u0655) وعلامات القرآن الصغيرة (\u0610–\u061A).
2. توحيد الألف — أ، إ، آ، ٱ تصبح ا.

وهو لا يوحّد التاء المربوطة (ة) ولا الألف المقصورة (ى): فذلك يُفقد معلومات نحوية يحتفظ بها المُقطِّع. أما البحث فيوحّدهما (§2.1).

2.1 العربية في البحث

تفهرس مكتبة المعرفة العربية وتبحث فيها بصيغة موحّدة واحدة، fold_for_search ‏(kazma_core/documents/arabic.py)، تُطبَّق على النص المخزَّن وعلى الاستعلام معًا: تُحذف الحركات والتطويل ومحارف التحكم في الاتجاه؛ وتُوحَّد صور الألف المهموزة والتاء المربوطة والألف المقصورة وحوامل الهمزة وصور الحروف الفارسية/الأردية؛ وتصير الأرقام العربية الهندية أرقامًا ASCII؛ وتُدمج المسافات. ويطبّع استرجاع الذاكرة كلمات السؤال وكلمات الذكرى بالطريقة نفسها (memory/query_terms.py)، ويُسقط كلمات الوقف الإنجليزية والخليجية/الفصحى (شنو، وش، شلون، وين، ليش، بس …) ويعالج أداة التعريف والسوابق أحادية الحرف (الذاكرة وRAG → recall()). لا يوجد مجذِّر للعربية (استكشاف الأخطاء ← النص العربي في البحث).

2.2 العربية في المستندات

يقرّر documents/arabic.py أيضًا الاتجاه (بحسب صنف bidi في Unicode)، ويشكّل العربية للمحركات التي تحتاج ذلك. القراءة: يعكس PyMuPDF كل سطر من اليمين إلى اليسار في ملف PDF، فتعيد كاظمه قراءة هذه الأسطر حرفًا حرفًا بحسب الرسوم (documents/parsers/pdf_rtl.py): فتعود الأرقام والحروف المركّبة وخلايا الجداول إلى ترتيب القراءة، ويُقرأ التاريخ المكتوب بعد كلمات عربية كما كُتب. ويستخدم التعرّف الضوئي (OCR) نموذجَي ara وeng في Tesseract، وتُقرأ الجداول المسطّرة في الصفحة الممسوحة خليةً خلية. والتعرّف الضوئي على العربية غير مؤهَّل: فـ Tesseract لا يقرأ الأرقام العربية الهندية، وقد يُسقط تحليلُه للتخطيط أسطرًا من الصفحة العربية. الكتابة: تأخذ كل كتلة من المستند المولَّد اتجاهها الخاص، فيُحاذي المستند ثنائي اللغة كلتا اللغتين محاذاةً صحيحة. وتمر ملفات PDF العربية بجودة كاملة عبر LibreOffice؛ ومن دونه تستخدم كاظمه بديلًا محدودًا وتقول ذلك. وكل هذا مقيس على مجموعة نصوص إنجليزية/عربية/ثنائية اللغة ذات إصدارات (ذكاء المستندات).

---

3. طبقة التدويل + واجهة RTL

3.1 نظام التدويل

kazma-ui/kazma_ui/i18n/ نظام تدويل مخصص وخفيف — ليس Babel/gettext. تعيش السلاسل كوحدة واحدة لكل قسم واجهة تحت i18n/catalog/ (بما فيها x_studio.py) وتندمج في TRANSLATIONS عند الاستيراد.

• لا ملفات ar.json/en.json منفصلة. المفاتيح سلاسل منقّطة بقيم {"en": ..., "ar": ...}.
• لا تُشحن سوى en وar افتراضيًا.
• كل مفتاح يجب أن يكون له مدخل en؛ وar يرتد إلى الإنجليزية إن غاب.

الواجهة:

الدالة	الغرض
t(key, lang, **kwargs)	ترجمة مع إقحام str.format.
t_plural(key, count, lang, **kwargs)	صيغة الجمع المناسبة لعدد — وللعربية ست صيغ.
make_translator(lang)	إغلاق مرتبط بلغة، لأجل Jinja2.
SUPPORTED_LANGUAGES	يُحسب ديناميكيًا من القاموس.

ترقيع Jinja2: ‏_patch_jinja2_templates() يرقّع قروديًا Jinja2Templates.__init__ ليحقن دائمًا عموميات التدويل الافتراضية (t، lang="en"، dir="ltr") فلا ترفع القوالب أبدًا UndefinedError. يُستدعى عند تحميل الوحدة.

التوصيل من جهة الخادم (app.py): يحقن الباني t وlang وdir وtranslations_json (القاموس كاملًا بصيغة JSON لAlpine.js على العميل) في عموميات Jinja2. يقرأ language_middleware ملف تعريف الارتباط kazma-lang ويضبط lang/dir لكل طلب. ومن دون ملف تعريف الارتباط تكون الصفحة بلغة التثبيت (agent.language). وتستدعي شيفرة Python التي تحتاج لغة الطلب i18n.current_language()؛ ولا يقرأ ملف تعريف الارتباط إلا الوسيط. وكانت أربعة مسارات تقرؤه بنفسها وتجعل الإنجليزية افتراضية، فعرض تثبيت عربي أجزاءً من لوحة التحكم بالإنجليزية.

3.2 التغطية

قاموس الترجمة واسع — تمتد المفاتيح على التنقل، والترويسة، والدردشة، ولوحة التحكم، والإعدادات، والسرب، والوكلاء، والمهارات، وMCP، ومساحة العمل، واستوديو X ‏(i18n/catalog/x_studio.py)، والمجدول. تعيش المدخلات كوحدة واحدة لكل قسم واجهة تحت kazma_ui/i18n/catalog/ وتُدمج عند الاستيراد، فيحافظ TRANSLATIONS على شكله. أمثلة: swarm.arabic_dialect، وswarm.dialect_msa (“Modern Standard Arabic” / “العربية الفصحى”).

3.3 معالجة RTL

• القالب: templates/base.html — <html lang="\{\{ lang()|default('en') \}\}" dir="\{\{ dir()|default('ltr') \}\}">.
• dir يكون "rtl" للعربية، ويضبطه وسيط اللغة لكل طلب.
• جهة العميل: يحقن base.html ‏window.KAZMA_LANG وبحث t() على العميل لتعابير Alpine.

النص يتبع لغته

لغة الواجهة تحدد تخطيط الصفحة وتسمياتها. ولا تحدد طريقة عرض النص: فالنص الإنجليزي يجري من اليسار إلى اليمين ويُحاذى إلى اليسار، والنص العربي يجري من اليمين إلى اليسار ويُحاذى إلى اليمين، في الواجهة العربية والواجهة الإنجليزية على السواء. وُضعت هذه القاعدة في 2026-10-02. وقبل ذلك كانت الواجهة العربية تحاذي الردود الإنجليزية ومخرجات الأدوات إلى اليمين، وكان الرد الإنجليزي في معظمه يعرض فقراته العربية من اليسار إلى اليمين في الواجهتين.

• المحاذاة منطقية. تستخدم أوراق الأنماط text-align: start، وتحسمها كل فقرة وفق اتجاهها هي. ولا تختار أي قاعدة left أو right بحسب dir الصفحة، إلا إذا صُرّح بها مع سببها (الشيفرة، والأرقام، ولوحات الرسوم البيانية).
• كل فقرة تأخذ اتجاهها. يعطي مُصيِّر Markdown ‏(streaming.js) كل فقرة وعنوان واقتباس وقائمة وعنصر قائمة وخلية جدول قيمة dir من كلماتها هي، عبر KazmaBidi.blockDir ‏(bidi.js). تأخذ الفقرة اللغة التي كُتبت بها أغلب كلماتها، ويُعدّ الرابط أو المسار أو المعرِّف كلمة واحدة. والكلمة التي فيها حرف عربي أو علامة ترقيم عربية كلمة عربية، فتُعدّ “وDOCX” و”Telegram،” عربيتين. والكلمة اللاتينية التي تبدو اسمًا (اختصار بأحرف كبيرة، أو CamelCase، أو كلمة فيها رقم، أو حرف كبير في وسط الجملة) تُحسب بربع كلمة، لأن الكتابة التقنية العربية مليئة بها: “WebDAV يعمل مع WD MyCloud OS5 وأي جهاز NAS” جملة عربية. وعند التعادل يحسم الحرف الأول. أما الكتلة التي لا حروف فيها، كالرقم، فتأخذ اتجاه حاويتها، فيبقى عمود الأرقام في جدول عربي على اليمين. وكان dir="auto" الخاص بالمتصفح ينظر إلى الحرف الأول وحده، فعرض “PDF الملف جاهز” من اليسار إلى اليمين.
• العزل يتبع الفقرة. يعزل مساعد الاتجاه الكلمات التي تخالف اتجاه فقرتها (اللاتينية في العربية، والعربية في الإنجليزية)، ولا يعزلها أبدًا وفق اتجاه الرسالة كلها.
• المحتوى مُعلَّم. البيانات التي تعرضها الصفحة (الأسماء، والعناوين، ومخرجات النموذج، والأخطاء، والمسارات) تحمل translate="no". وتعطي قاعدة عامة ذلك العنصر وكل كتلة داخله اتجاهه من نصه هو (unicode-bidi: plaintext)، إلا العنصر الذي ضبط سكربتٌ قيمة dir له من قبل، كفقرة حدّد المُصيِّر اتجاهها أو استدعاء أداة يبقى من اليسار إلى اليمين. أما كلمات الواجهة داخل المحتوى (translate="yes") فتتبع الصفحة. وتشمل القاعدة نفسها ما تكتبه في حقل. ولا تُعلَّم الأرقام، لأن القيمة التي لا حروف فيها تُعرض من اليسار إلى اليمين.
• السطر الذي يخلط تسمية بمحتوى يُفصل. في صف «الذاكرة المستخدمة» في لوحة النشاط، كل ذكرى في سطر خاص بها بلغتها، وتسمية نوعها معزولة عنها. وفي الواجهة العربية كانت التسمية تحدد اتجاه السطر كله.
• الرد يبدو واحدًا في الواجهتين. لا تحاذي أي قاعدة في أوراق الأنماط مرتبطة باتجاه الصفحة فقاعةَ محادثة.

البوابات: tests/test_text_follows_its_language.py (أوراق الأنماط، وروابط القوالب، وملف تعريف الارتباط) وtests/e2e/test_text_follows_its_language.py. يرسل اختبار المتصفح أدوارًا حقيقية عبر صفحة المحادثة في الواجهتين، ويقيس موضع كل سطر من كل فقرة ومن مخرجات الأدوات، مباشرةً وبعد إعادة التحميل، ويشترط أن تعرض الواجهتان كل فقرة بالطريقة نفسها. ويغطي tests/js/test_block_direction.js قاعدة الفقرة والمُصيِّر.

3.4 سياسة الخط العربي (IBM Plex، حجم متساوٍ EN/AR)

kazma-ui/kazma_ui/static/css/kazma.css — IBM Plex Sans / IBM Plex Sans Arabic هو الوجه المشترك مع المستندات المولّدة (style_theme.THEME) ووثائق Docusaurus. يبقى أميري احتياطًا نسخيًا عند غياب Plex. حرف الترويسة K هو شعار المنتج والأيقونة والصورة الرمزية.

تتشارك EN وAR الجذر نفسه 14px. يوازي Plex Arabic الحجم البصري اللاتيني، لذا كان رفع الأساس لRTL فقط (الـ16px القديم / مضاعف 1.15×) يجعل الواجهة كلها أكبر. ما زالت للتسميات الدقيقة أرضية قراءة (~11px) لأن العربية بحجم 0.6–0.7rem غير مقروءة. منزلق حجم الخط في الإعدادات هو أداة تحكم المشغّل بالحجم وينطبق بالتساوي على اللغتين.

/* Font stacks (kazma.css :root) */
:root {
  --font-sans: 'IBM Plex Sans', 'IBM Plex Sans Arabic', system-ui, ...;
  --font-arabic: 'IBM Plex Sans Arabic', 'IBM Plex Sans', system-ui, ...;
  --font-mono: 'JetBrains Mono', 'SF Mono', 'Fira Code', monospace;
}

html { font-size: 14px; }

html[dir="rtl"] .badge,
html[dir="rtl"] .metric-label,
html[dir="rtl"] .text-muted,
html[dir="rtl"] .text-xs { font-size: 0.82rem !important; }

[dir="rtl"] body,
[dir="rtl"] input,
[dir="rtl"] textarea,
[dir="rtl"] button,
[dir="rtl"] select { font-family: var(--font-arabic); }

Plex هو الخط الأساسي لكلٍّ من اللاتينية والعربية. الأرقام الجدولية (tnum) تُطبَّق على LTR فقط — لا تفرض أبدًا ميزات OpenType اللاتينية على العربية.

---

4. بروتوكول المجلس

kazma-core/kazma_core/majlis.py. الحالة: التحية والوداع فقط (§4.5).

4.1 ما هو

الصنف MajlisProtocol. من سلسلة توثيق الوحدة:

بروتوكول المجلس — بروتوكول محادثة ثقافي لتفاعلات العربية الخليجية. المجلس (مجلس) هو فضاء التجمع الخليجي التقليدي حيث تتبع المحادثة إيقاعات ثقافية محددة: التحية أولًا، ثم الحديث الاجتماعي، ثم العمل.

4.2 تدفق الأطوار الأربعة

التعداد ConversationPhase:

flowchart LR
    G[GREETING] --> S[SOCIAL]
    S --> T[TRANSACTION]
    T --> F[FAREWELL]

الطور	الغرض
GREETING	التحية أولًا (السلام عليكم، هلا والله، شلونك).
SOCIAL	حديث اجتماعي قبل العمل.
TRANSACTION	المهمة/الطلب الفعلي.
FAREWELL	مجاملات الختام.

4.3 الافتراضيات والمعدِّلات الثقافية

• اللهجة الافتراضية: الكويتية (dialect: str = "kw").
• أنماط تحية/وداع كويتية مدمجة في الشيفرة (GREETING_PATTERNS، FAREWELL_PATTERNS): "السلام عليكم"، و"هلا والله"، و"شلونك"، إلخ.
• المعدِّلات الثقافية: رمضان والعيد واليوم الوطني تعدّل طول طور التحية ورسميته.
• الوحدات الشقيقة: CulturalContext، وConversationPacing/Intent/TransitionDecision، وToneAdapter/FormalityLevel.

4.4 الواجهة

• process_input(text, context) — نقطة دخول غير متزامنة، يعيد MajlisResponse.

4.5 النطاق (ملاحظة صادقة)

يعيش المجلس في kazma-core. على مسار تطبيقات الدردشة (تيليجرام وديسكورد وسلاك) يجيب majlis_runtime.maybe_majlis_short_circuit — المستدعى من kazma_gateway/agent_handler/graph.py — عن تحية أو وداع قصير عبر MajlisProtocol.process_input؛ أما المحادثة العادية فلا تدخل آلة الأطوار. ويعمل تكييف النبرة وإثراء السياق الثقافي بجانبه على ذلك المسار، ويحمل موجّه نظام الوكيل تعليمة باللهجة الكويتية/الخليجية للردود العربية (cultural_context_enrichment.py). لا يوجد مفتاح «وضع المجلس» في إعدادات الويب ولا مفاتيح تدويل له. توجد اختبارات في tests/test_majlis.py، ويعيش مثال في examples/almuhalab_custom_skills/trading_intel/.

---

5. توطين TUI

لTUI توطين/اتجاه خاص بها (kazma_tui/app.py):

• update_localization() يبدّل صنف CSS ‏rtl-mode ويترجم تسميات التبويبات وشريط التنقل من جدول واحد، TAB_LABELS ‏(kazma_tui/nav_rail.py). والصفحة الموجودة في واجهة الويب أيضًا تأخذ كلمة الويب (لوحة التحكم هي لوحة التحكم في الاثنتين).
• Ctrl+L يبدّل بين الإنجليزية والعربية (وكذلك في لوحة الأوامر، Switch language)، ويُحفظ الاختيار.

---

6. دعم اللهجات

دليل اللهجة	الموضع
العلامات الكويتية (كشف اللهجة)	arabic/kuwaiti_lexicon.py ‏(CANONICAL_KUWAITI_MARKERS)، ويقرؤها dialect_detector.py
كلمات الوقف الخليجية/الفصحى (بحث الذاكرة)	memory/query_terms.py ‏(شنو، وش، شلون، وين، ليش، بس …)
الردود الكويتية/الخليجية بالعربية	cultural_context_enrichment.py (تعليمة اللهجة في موجّه النظام)
اللهجة الكويتية الافتراضية	majlis.py ‏(dialect: str = "kw")
أنماط تحية/وداع كويتية	majlis.py ‏(GREETING_PATTERNS، FAREWELL_PATTERNS)
تسمية واجهة الفصحى (Modern Standard Arabic)	kazma_ui/i18n/catalog/swarm.py ‏(swarm.dialect_msa)
مفتاح الإعداد swarm.arabic_dialect	kazma_ui/i18n/catalog/swarm.py

---

7. ملاحظات استخدام ثنائية اللغة

• الافتراضي المشحون هو الإنجليزية (agent.language: en، agent.rtl: false). اضبط ar وtrue لتثبيت يقدّم العربية.
• ملف تعريف الارتباط kazma-lang يبدّل لغة واجهة الويب لكل متصفح دون إعادة تشغيل.
• يجعل system_prompt في kazma.yaml النموذجَ يجيب بلغة آخر رسالة من المستخدم (والمزيج بمزيج) ويسمّي نفسه كاظمه بالعربية؛ وقفل اللغة لكل دور يعلو عليه.
• للنشر ثنائي اللغة، فكّر في توفير أمثلة EN وAR معًا في المهارات/الأدوات حيث تكون لغة المخرجات مهمة.

---

ملاحظات تدقيق الوثائق

• المجلس موصول للتحية والوداع فقط، على مسار تطبيقات الدردشة (§4.5).
• المجلس ليس ميزة واجهة. لا يوجد مفتاح إعدادات أو مفتاح تدويل ل«وضع المجلس». إنه بروتوكول محادثة أساسي.
• لا ملفات ترجمة منفصلة. تعيش سلاسل EN/AR في kazma_ui/i18n/catalog/، وحدة لكل قسم واجهة؛ ويضيف المساهمون مفتاحًا إلى وحدة قسمه.
• المُقطِّعات وتوحيد البحث والتدويل مستقلة. تغيير التدويل لا يؤثر في فهرسة البحث، ولا تؤثر مُقطِّعات اللهجة في البحث كذلك.