إنشاء وحدات إضافية جديدة¶

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

المفهوم الأساسي: الوحدات المستندة إلى المجلدات¶

الوحدة هي ببساطة مجلد داخل الدليل config/maps/. يقوم النظام تلقائيًا بمسح هذا الدليل ويعامل كل مجلد فرعي كوحدة نمطية قابلة للتحميل.

        ### دليل خطوة بخطوة لإنشاء وحدة نمطية

اتبع هذه الخطوات لإنشاء وحدة نمطية جديدة، على سبيل المثال، للاحتفاظ بوحدات الماكرو الخاصة بلعبة معينة.

                         **1. انتقل إلى دليل الخرائط**

جميع وحدات القاعدة موجودة في مجلد “config/maps/” الخاص بالمشروع.

         **2. قم بإنشاء مجلد الوحدة الخاصة بك**

قم بإنشاء مجلد جديد. يجب أن يكون الاسم وصفيًا وأن يستخدم الشرطات السفلية بدلاً من المسافات (على سبيل المثال، my_game_macros، custom_home_automation).

 **3. إضافة مجلدات فرعية للغة (خطوة حاسمة)**

داخل مجلد الوحدة النمطية الجديد، يجب عليك إنشاء مجلدات فرعية لكل لغة تنوي دعمها.

اصطلاح التسمية: أسماء هذه المجلدات الفرعية يجب أن تكون رموز لغة محلية صالحة. يستخدم النظام هذه الأسماء لتحميل القواعد الصحيحة للغة النشطة.
- الأمثلة الصحيحة: de-DE، en-US، en-GB، pt-BR
تحذير: إذا كنت تستخدم اسمًا غير قياسي مثل الألمانية أو قواعد_الإنجليزية، فسيتجاهل النظام المجلد أو سيتعامل معه كوحدة منفصلة غير خاصة باللغة.
```
              **4. أضف ملفات القاعدة الخاصة بك**
```

ضع ملفات القاعدة (على سبيل المثال، FUZZY_MAP_pre.py) داخل المجلد الفرعي للغة المناسب. أسهل طريقة للبدء هي نسخ محتويات مجلد وحدة اللغة الموجود لاستخدامه كقالب.

                                ### مثال على بنية الدليل

config/
└── maps/
    ├── standard_actions/      # An existing module
    │   ├── de-DE/
    │   └── en-US/
    │
    └── my_game_macros/        # <-- Your new custom module
        └── de-DE/             # <-- Language-specific rules
            └── FUZZY_MAP_pre.py

        ├── __init__.py        # <-- Important: This Empty File must be in every Folders!!
            

                        ### إدارة الوحدات في التكوين

تم تصميم النظام بحيث يتطلب الحد الأدنى من التكوين.

                      #### تمكين الوحدات (الافتراضي)

يتم تمكين الوحدات افتراضيًا **. طالما أن مجلد الوحدة موجود في config/maps/، فسيقوم النظام بالبحث عنه وتحميل قواعده. لست بحاجة إلى إضافة إدخال إلى ملف الإعدادات الخاص بك لتمكين وحدة جديدة.

                                           #### تعطيل الوحدات

لتعطيل وحدة نمطية، يجب عليك إضافة إدخال لها في قاموس PLUGINS_ENABLED داخل ملف الإعدادات الخاص بك وتعيين قيمته على False.

                                     **مثال (`config/settings.py`):**

# A dictionary to explicitly control the state of modules.
# The key is the path to the module relative to 'config/maps/'.
PLUGINS_ENABLED = {
    "empty_all": False,

    # This module is explicitly enabled.
    "git": True,

    # This module is also enabled. Second Parameter is per default True. Not False means True.
    # "wannweil": False,

    # This module is explicitly disabled.
    "game": False,

    # This module is disabled by other rule
    "game/game-dealers_choice": True,

    # This module is disabled by other rule
    "game/0ad": True,
}

                           ### ملاحظات التصميم الهامة

السلوك الافتراضي: لا يوجد إدخال يساوي صحيح إذا لم تكن الوحدة مدرجة في القاموس PLUGINS_ENABLED، فسيتم اعتبارها نشطة بشكل افتراضي. يحافظ هذا التصميم على نظافة ملف التكوين، حيث أنك تحتاج فقط إلى إدراج الاستثناءات.
```
                                    * ** اختصار للتمكين **
```

يدرك نظام التكوين الخاص بك أيضًا أن إدراج مفتاح الوحدة بدون قيمة يعني أنه تم تمكينه. على سبيل المثال، إضافة "wannweil" إلى القاموس هي نفس إضافة "wannweil": True. يوفر هذا اختصارًا مناسبًا لتمكين الوحدات النمطية.

تعطيل الوحدات الأصلية: السلوك المقصود هو أن تعطيل الوحدة الأصلية يجب أن يكون XSPACEbreakX قم تلقائيًا بتعطيل جميع الوحدات الفرعية ومجلدات اللغة الفرعية الخاصة به. على سبيل المثال، يجب أن يؤدي إعداد "standard_actions": False إلى منع تحميل كل من de-DE وen-US`. (27.10.25 الإثنين) اكس سبيس بريك اكس * هدف الهدف هو تعزيز هذا النظام بشكل أكبر. على سبيل المثال، توفير طريقة لاحترام إعدادات الوحدة الفرعية حتى إذا تم تعطيل الأصل، أو تقديم قواعد وراثة أكثر تعقيدًا. (27.10.25 الإثنين)