Web-Dev-For-Beginners/translations/ar/AGENTS.md

AGENTS.md

نظرة عامة على المشروع

هذا مستودع منهجي تعليمي لتعليم أساسيات تطوير الويب للمبتدئين. المنهج عبارة عن دورة شاملة لمدة 12 أسبوعًا تم تطويرها بواسطة Microsoft Cloud Advocates، ويشمل 24 درسًا عمليًا يغطي JavaScript وCSS وHTML.

المكونات الرئيسية

• المحتوى التعليمي: 24 درسًا منظمًا في وحدات قائمة على المشاريع
• المشاريع العملية: Terrarium، لعبة الكتابة، إضافة المتصفح، لعبة الفضاء، تطبيق البنك، محرر الأكواد، ومساعد الدردشة بالذكاء الاصطناعي
• الاختبارات التفاعلية: 48 اختبارًا يحتوي كل منها على 3 أسئلة (تقييمات قبل وبعد الدرس)
• دعم متعدد اللغات: ترجمات تلقائية لأكثر من 50 لغة عبر GitHub Actions
• التقنيات: HTML، CSS، JavaScript، Vue.js 3، Vite، Node.js، Express، Python (للمشاريع المتعلقة بالذكاء الاصطناعي)

الهيكلية

• مستودع تعليمي مع هيكلية قائمة على الدروس
• يحتوي كل مجلد درس على README، أمثلة أكواد، وحلول
• مشاريع مستقلة في أدلة منفصلة (quiz-app، مشاريع الدروس المختلفة)
• نظام ترجمة باستخدام GitHub Actions (co-op-translator)
• الوثائق تُعرض عبر Docsify ومتاحة كملف PDF

أوامر الإعداد

هذا المستودع مخصص بشكل أساسي لاستهلاك المحتوى التعليمي. للعمل مع مشاريع محددة:

إعداد المستودع الرئيسي

git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners

إعداد تطبيق الاختبارات (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Start development server
npm run build      # Build for production
npm run lint       # Run ESLint

إعداد واجهة برمجة تطبيقات البنك (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Start API server
npm run lint       # Run ESLint
npm run format     # Format with Prettier

مشاريع إضافات المتصفح

cd 5-browser-extension/solution
npm install
# Follow browser-specific extension loading instructions

مشاريع لعبة الفضاء

cd 6-space-game/solution
npm install
# Open index.html in browser or use Live Server

مشروع الدردشة (Python Backend)

cd 9-chat-project/solution/backend/python
pip install openai
# Set GITHUB_TOKEN environment variable
python api.py

سير العمل التطويري

للمساهمين في المحتوى

1. قم بعمل Fork للمستودع إلى حساب GitHub الخاص بك
2. قم باستنساخ النسخة الخاصة بك محليًا
3. أنشئ فرعًا جديدًا للتعديلات الخاصة بك
4. قم بإجراء تغييرات على محتوى الدروس أو أمثلة الأكواد
5. اختبر أي تغييرات في الأكواد في أدلة المشاريع ذات الصلة
6. قدم طلبات السحب وفقًا لإرشادات المساهمة

للمتعلمين

1. قم بعمل Fork أو استنساخ المستودع
2. انتقل إلى أدلة الدروس بالتسلسل
3. اقرأ ملفات README لكل درس
4. أكمل اختبارات ما قبل الدرس على https://ff-quizzes.netlify.app/web/
5. اعمل على أمثلة الأكواد في مجلدات الدروس
6. أكمل المهام والتحديات
7. قم بأداء اختبارات ما بعد الدرس

التطوير المباشر

• الوثائق: قم بتشغيل docsify serve في الجذر (المنفذ 3000)
• تطبيق الاختبارات: قم بتشغيل npm run dev في دليل quiz-app
• المشاريع: استخدم إضافة Live Server في VS Code لمشاريع HTML
• مشاريع واجهة برمجة التطبيقات: قم بتشغيل npm start في أدلة واجهة برمجة التطبيقات ذات الصلة

تعليمات الاختبار

اختبار تطبيق الاختبارات

cd quiz-app
npm run lint       # Check for code style issues
npm run build      # Verify build succeeds

اختبار واجهة برمجة تطبيقات البنك

cd 7-bank-project/api
npm run lint       # Check for code style issues
node server.js     # Verify server starts without errors

نهج الاختبار العام

• هذا مستودع تعليمي بدون اختبارات آلية شاملة
• يركز الاختبار اليدوي على:
  • تشغيل أمثلة الأكواد بدون أخطاء
  • عمل الروابط في الوثائق بشكل صحيح
  • اكتمال بناء المشاريع بنجاح
  • اتباع الأمثلة لأفضل الممارسات

الفحوصات قبل التقديم

• قم بتشغيل npm run lint في الأدلة التي تحتوي على package.json
• تحقق من صحة روابط Markdown
• اختبر أمثلة الأكواد في المتصفح أو Node.js
• تأكد من أن الترجمات تحافظ على الهيكل الصحيح

إرشادات نمط الأكواد

JavaScript

• استخدم صيغة ES6+ الحديثة
• اتبع تكوينات ESLint القياسية المقدمة في المشاريع
• استخدم أسماء متغيرات ووظائف ذات معنى لتوضيح التعليم
• أضف تعليقات تشرح المفاهيم للمتعلمين
• قم بالتنسيق باستخدام Prettier حيث تم تكوينه

HTML/CSS

• عناصر HTML5 دلالية
• مبادئ التصميم المتجاوب
• اتفاقيات تسمية واضحة للفئات
• تعليقات تشرح تقنيات CSS للمتعلمين

Python

• إرشادات نمط PEP 8
• أمثلة أكواد واضحة وتعليمية
• تلميحات النوع حيث تكون مفيدة للتعلم

وثائق Markdown

• تسلسل واضح للعناوين
• كتل الأكواد مع تحديد اللغة
• روابط إلى موارد إضافية
• لقطات وصور في أدلة images/
• نص بديل للصور لتحسين الوصول

تنظيم الملفات

• الدروس مرقمة بالتسلسل (1-getting-started-lessons، 2-js-basics، إلخ)
• يحتوي كل مشروع على solution/ وغالبًا start/ أو your-work/ أدلة
• الصور مخزنة في مجلدات images/ الخاصة بالدروس
• الترجمات في هيكل translations/{language-code}/

البناء والنشر

نشر تطبيق الاختبارات (Azure Static Web Apps)

تم تكوين quiz-app للنشر عبر Azure Static Web Apps:

cd quiz-app
npm run build      # Creates dist/ folder
# Deploys via GitHub Actions workflow on push to main

تكوين Azure Static Web Apps:

• موقع التطبيق: /quiz-app
• موقع الإخراج: dist
• سير العمل: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

إنشاء وثائق PDF

npm install                    # Install docsify-to-pdf
npm run convert               # Generate PDF from docs

وثائق Docsify

npm install -g docsify-cli    # Install Docsify globally
docsify serve                 # Serve on localhost:3000

عمليات بناء المشاريع المحددة

قد يحتوي كل دليل مشروع على عملية بناء خاصة به:

• مشاريع Vue: npm run build لإنشاء حزم الإنتاج
• المشاريع الثابتة: لا توجد خطوة بناء، قم بخدمة الملفات مباشرة

إرشادات طلب السحب

تنسيق العنوان

استخدم عناوين واضحة وواصفة تشير إلى منطقة التغيير:

• [Quiz-app] إضافة اختبار جديد للدرس X
• [Lesson-3] إصلاح خطأ في مشروع terrarium
• [Translation] إضافة ترجمة إسبانية للدرس 5
• [Docs] تحديث تعليمات الإعداد

الفحوصات المطلوبة

قبل تقديم طلب السحب:

1. جودة الأكواد:

   • قم بتشغيل npm run lint في أدلة المشاريع المتأثرة
   • أصلح جميع أخطاء وتحذيرات التحقق

2. التحقق من البناء:

   • قم بتشغيل npm run build إذا كان ذلك ممكنًا
   • تأكد من عدم وجود أخطاء في البناء

3. التحقق من الروابط:

   • اختبر جميع روابط Markdown
   • تحقق من عمل مراجع الصور

4. مراجعة المحتوى:

   • قم بمراجعة الأخطاء الإملائية والنحوية
   • تأكد من صحة أمثلة الأكواد وتعليمها
   • تحقق من أن الترجمات تحافظ على المعنى الأصلي

متطلبات المساهمة

• الموافقة على Microsoft CLA (التحقق الآلي عند أول طلب سحب)
• اتباع مدونة قواعد السلوك المفتوحة المصدر من Microsoft
• راجع CONTRIBUTING.md للحصول على إرشادات مفصلة
• أشر إلى أرقام القضايا في وصف طلب السحب إذا كان ذلك ممكنًا

عملية المراجعة

• يتم مراجعة طلبات السحب بواسطة المشرفين والمجتمع
• يتم إعطاء الأولوية للوضوح التعليمي
• يجب أن تتبع أمثلة الأكواد أفضل الممارسات الحالية
• يتم مراجعة الترجمات للتأكد من دقتها وملاءمتها الثقافية

نظام الترجمة

الترجمة التلقائية

• يستخدم GitHub Actions مع سير عمل co-op-translator
• يترجم تلقائيًا إلى أكثر من 50 لغة
• الملفات المصدر في الأدلة الرئيسية
• الملفات المترجمة في هيكل translations/{language-code}/

إضافة تحسينات الترجمة اليدوية

1. حدد الملف في translations/{language-code}/
2. قم بإجراء تحسينات مع الحفاظ على الهيكل
3. تأكد من أن أمثلة الأكواد تظل وظيفية
4. اختبر أي محتوى اختبارات محلي

بيانات الترجمة الوصفية

تتضمن الملفات المترجمة رأس بيانات وصفية:

<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->

تصحيح الأخطاء واستكشاف المشكلات

المشكلات الشائعة

فشل تشغيل تطبيق الاختبارات:

• تحقق من إصدار Node.js (يوصى بـ v14+)
• احذف node_modules وpackage-lock.json، ثم قم بتشغيل npm install مرة أخرى
• تحقق من تعارض المنافذ (الافتراضي: يستخدم Vite المنفذ 5173)

فشل تشغيل خادم واجهة برمجة التطبيقات:

• تحقق من أن إصدار Node.js يلبي الحد الأدنى (node >=10)
• تحقق مما إذا كان المنفذ قيد الاستخدام بالفعل
• تأكد من تثبيت جميع التبعيات باستخدام npm install

فشل تحميل إضافة المتصفح:

• تحقق من أن manifest.json تم تنسيقه بشكل صحيح
• تحقق من أخطاء وحدة التحكم في المتصفح
• اتبع تعليمات تثبيت الإضافة الخاصة بالمتصفح

مشكلات مشروع الدردشة Python:

• تأكد من تثبيت حزمة OpenAI: pip install openai
• تحقق من تعيين متغير البيئة GITHUB_TOKEN
• تحقق من أذونات الوصول إلى نماذج GitHub

Docsify لا يعرض الوثائق:

• قم بتثبيت docsify-cli عالميًا: npm install -g docsify-cli
• قم بتشغيله من دليل الجذر للمستودع
• تحقق من وجود docs/_sidebar.md

نصائح بيئة التطوير

• استخدم VS Code مع إضافة Live Server لمشاريع HTML
• قم بتثبيت إضافات ESLint وPrettier للتنسيق المتسق
• استخدم أدوات DevTools في المتصفح لتصحيح أخطاء JavaScript
• لمشاريع Vue، قم بتثبيت إضافة Vue DevTools للمتصفح

اعتبارات الأداء

• العدد الكبير من الملفات المترجمة (50+ لغة) يعني أن النسخ الكامل كبير
• استخدم النسخ الضحل إذا كنت تعمل فقط على المحتوى: git clone --depth 1
• استبعد الترجمات من عمليات البحث عند العمل على المحتوى باللغة الإنجليزية
• قد تكون عمليات البناء بطيئة في التشغيل الأول (npm install، Vite build)

اعتبارات الأمان

متغيرات البيئة

• يجب ألا يتم الالتزام بمفاتيح واجهة برمجة التطبيقات إلى المستودع
• استخدم ملفات .env (موجودة بالفعل في .gitignore)
• قم بتوثيق متغيرات البيئة المطلوبة في ملفات README الخاصة بالمشاريع

مشاريع Python

• استخدم البيئات الافتراضية: python -m venv venv
• حافظ على تحديث التبعيات
• يجب أن تحتوي رموز الوصول إلى GitHub على الحد الأدنى من الأذونات المطلوبة

الوصول إلى نماذج GitHub

• مطلوب رموز الوصول الشخصي (PAT) لنماذج GitHub
• يجب تخزين الرموز كمتغيرات بيئة
• لا تقم أبدًا بالالتزام بالرموز أو بيانات الاعتماد

ملاحظات إضافية

الجمهور المستهدف

• المبتدئين تمامًا في تطوير الويب
• الطلاب والمتعلمين ذاتيًا
• المعلمون الذين يستخدمون المنهج في الفصول الدراسية
• المحتوى مصمم ليكون سهل الوصول وبناء المهارات تدريجيًا

فلسفة التعليم

• نهج التعلم القائم على المشاريع
• فحوصات المعرفة المتكررة (اختبارات)
• تمارين البرمجة العملية
• أمثلة تطبيقية من العالم الحقيقي
• التركيز على الأساسيات قبل الإطارات

صيانة المستودع

• مجتمع نشط من المتعلمين والمساهمين
• تحديثات منتظمة للتبعيات والمحتوى
• يتم مراقبة القضايا والمناقشات بواسطة المشرفين
• تحديثات الترجمة تلقائية عبر GitHub Actions

الموارد ذات الصلة

• وحدات Microsoft Learn
• موارد مركز الطلاب
• GitHub Copilot موصى به للمتعلمين
• دورات إضافية: الذكاء الاصطناعي التوليدي، علم البيانات، التعلم الآلي، مناهج إنترنت الأشياء متاحة

العمل مع مشاريع محددة

للحصول على تعليمات مفصلة حول المشاريع الفردية، راجع ملفات README في:

• quiz-app/README.md - تطبيق الاختبارات Vue 3
• 7-bank-project/README.md - تطبيق البنك مع المصادقة
• 5-browser-extension/README.md - تطوير إضافات المتصفح
• 6-space-game/README.md - تطوير الألعاب القائمة على Canvas
• 9-chat-project/README.md - مشروع مساعد الدردشة بالذكاء الاصطناعي

هيكلية Monorepo

على الرغم من أنه ليس مستودعًا تقليديًا متعدد المشاريع، يحتوي هذا المستودع على مشاريع مستقلة متعددة:

• كل درس مكتفٍ ذاتيًا
• المشاريع لا تشترك في التبعيات
• العمل على المشاريع الفردية دون التأثير على الآخرين
• استنساخ المستودع بالكامل لتجربة المنهج الكامل

---

إخلاء المسؤولية:
تم ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي Co-op Translator. بينما نسعى لتحقيق الدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو معلومات غير دقيقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الموثوق. للحصول على معلومات حاسمة، يُوصى بالاستعانة بترجمة بشرية احترافية. نحن غير مسؤولين عن أي سوء فهم أو تفسيرات خاطئة ناتجة عن استخدام هذه الترجمة.