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

AGENTS.md

نمای کلی پروژه

این یک مخزن برنامه درسی آموزشی برای آموزش مبانی توسعه وب به مبتدیان است. این برنامه درسی یک دوره جامع ۱۲ هفته‌ای توسعه یافته توسط مدافعان ابر مایکروسافت است که شامل ۲۴ درس عملی در زمینه‌های JavaScript، CSS و HTML می‌باشد.

اجزای کلیدی

• محتوای آموزشی: ۲۴ درس سازمان‌یافته در قالب ماژول‌های پروژه‌محور
• پروژه‌های عملی: Terrarium، بازی تایپ، افزونه مرورگر، بازی فضایی، برنامه بانکداری، ویرایشگر کد، و دستیار چت هوش مصنوعی
• آزمون‌های تعاملی: ۴۸ آزمون با ۳ سوال هر کدام (ارزیابی قبل و بعد درس)
• پشتیبانی چندزبانه: ترجمه‌های خودکار به بیش از ۵۰ زبان از طریق 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        # شروع سرور توسعه
npm run build      # ساخت برای تولید
npm run lint       # اجرای ESLint

API پروژه بانک (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # شروع سرور API
npm run lint       # اجرای ESLint
npm run format     # قالب‌بندی با Prettier

پروژه‌های افزونه مرورگر

cd 5-browser-extension/solution
npm install
# دستورالعمل‌های بارگذاری افزونه خاص مرورگر را دنبال کنید

پروژه‌های بازی فضایی

cd 6-space-game/solution
npm install
# فایل index.html را در مرورگر باز کنید یا از سرور زنده استفاده کنید

پروژه چت (بک‌اند پایتون)

cd 9-chat-project/solution/backend/python
pip install openai
# تنظیم متغیر محیطی GITHUB_TOKEN
python api.py

روند توسعه

برای مشارکت‌کنندگان محتوا

1. فورک کردن مخزن در حساب GitHub خود
2. کلون کردن فورک به صورت محلی
3. ایجاد شاخه جدید برای تغییرات
4. اعمال تغییرات در محتوای درس یا نمونه کدها
5. تست تغییرات کد در دایرکتوری‌های پروژه مرتبط
6. ارسال درخواست‌های pull طبق دستورالعمل‌های مشارکت

برای یادگیرندگان

1. فورک یا کلون کردن مخزن
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
• پروژه‌های API: اجرای npm start در دایرکتوری‌های مربوطه

دستورالعمل‌های تست

تست اپلیکیشن آزمون

cd quiz-app
npm run lint       # بررسی مشکلات سبک کد
npm run build      # اطمینان از موفقیت ساخت

تست API بانک

cd 7-bank-project/api
npm run lint       # بررسی مشکلات سبک کد
node server.js     # اطمینان از شروع سرور بدون خطاها

رویکرد کلی تست

• این مخزن آموزشی فاقد تست‌های خودکار جامع است
• تست دستی بر موارد زیر تمرکز دارد:
  • اجرای بدون خطای نمونه کدها
  • عملکرد صحیح لینک‌های مستندات
  • کامپایل موفق پروژه‌ها
  • پیروی نمونه‌ها از بهترین شیوه‌ها

بررسی‌های پیش از ارسال

• اجرای npm run lint در دایرکتوری‌های دارای package.json
• اطمینان از اعتبار لینک‌های markdown
• تست نمونه کدها در مرورگر یا Node.js
• بررسی ساختار درست ترجمه‌ها

راهنمایی‌های سبک کدنویسی

جاوااسکریپت

• استفاده از نحو ES6+ مدرن
• پیروی از تنظیمات ESLint استاندارد پروژه‌ها
• استفاده از نام‌های معنادار متغیرها و توابع برای وضوح آموزشی
• افزودن کامنت‌های توضیحی برای مفاهیم
• فرمت کد با Prettier در صورت تنظیم

HTML/CSS

• استفاده از عناصر معنایی HTML5
• اصول طراحی واکنش‌گرا
• نام‌گذاری کلاس‌ها به صورت واضح
• کامنت‌هایی برای توضیح تکنیک‌های CSS برای یادگیرندگان

پایتون

• پیروی از قوانین سبک PEP 8
• نمونه کدهای واضح و آموزشی
• استفاده از تایپ هینت‌ها در صورت امکان و مفید بودن برای یادگیری

مستندسازی مارک‌داون

• سلسله مراتب هدینگ واضح
• بلوک‌های کد با تعیین زبان
• لینک به منابع اضافی
• اسکرین‌شات‌ها و تصاویر داخل پوشه‌های 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      # ایجاد پوشه dist/
# استقرار از طریق گردش کار GitHub Actions هنگام فشار به شاخه main

پیکربندی Azure Static Web Apps:

• مکان برنامه: /quiz-app
• مکان خروجی: dist
• فرآیند کاری: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

تولید PDF مستندات

npm install                    # نصب docsify-to-pdf
npm run convert               # تولید PDF از docs

مستندسازی با Docsify

npm install -g docsify-cli    # نصب Docsify به صورت سراسری
docsify serve                 # سرویس‌دهی در localhost:3000

ساخت‌های مخصوص پروژه

هر دایرکتوری پروژه ممکن است روند ساخت خاص خود را داشته باشد:

• پروژه‌های Vue: اجرای npm run build بسته‌های پروداکشن ایجاد می‌کند
• پروژه‌های استاتیک: بدون مرحله ساخت، فایل‌ها مستقیماً سرو می‌شوند

دستورالعمل‌های ارسال Pull Request

قالب عنوان

از عناوین واضح و توصیفی با اشاره به حوزه تغییر استفاده کنید:

• [Quiz-app] افزودن آزمون جدید برای درس X
• [درس-3] اصلاح غلط املایی در پروژه terrarium
• [ترجمه] افزودن ترجمه اسپانیایی برای درس 5
• [مستندات] به‌روزرسانی دستورالعمل‌های راه‌اندازی

بررسی‌های اجباری

قبل از ارسال PR:

1. کیفیت کد:

   • اجرای npm run lint در دایرکتوری‌های پروژه مربوطه
   • اصلاح تمام خطاها و هشدارهای lint

2. تأیید ساخت:

   • اجرای npm run build در صورت لزوم
   • اطمینان از عدم وجود خطا در ساخت

3. اعتبارسنجی لینک‌ها:

   • تست تمام لینک‌های markdown
   • اطمینان از عملکرد لینک تصاویر

4. بازبینی محتوا:

   • بازخوانی برای غلط‌های املایی و گرامری
   • اطمینان از درستی و آموزشی بودن نمونه کدها
   • تأیید حفظ معنی اصلی ترجمه‌ها

نیازمندی‌های مشارکت

• توافق با CLA مایکروسافت (بررسی خودکار در اولین PR)
• پیروی از کد رفتار منبع باز مایکروسافت
• مشاهده CONTRIBUTING.md برای دستورالعمل‌های دقیق
• ارجاع شماره مسائل در توضیحات PR در صورت لزوم

فرایند بازبینی

• بازبینی PRها توسط نگه‌داران و جامعه
• اولویت به وضوح آموزشی
• نمونه کدها باید بهترین شیوه‌های جاری را رعایت کنند
• بررسی ترجمه‌ها برای دقت و مناسب بودن فرهنگی

سیستم ترجمه

ترجمه خودکار

• استفاده از GitHub Actions با workflow co-op-translator
• ترجمه خودکار به بیش از ۵۰ زبان
• فایل‌های منبع در دایرکتوری‌های اصلی
• فایل‌های ترجمه شده در ساختار 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 برابر ۵۱۷۳ است)

سرور API راه‌اندازی نمی‌شود:

• اطمینان از حداقل نسخه Node.js (node >=10)
• بررسی استفاده بودن پورت
• اطمینان از نصب تمامی وابستگی‌ها با npm install

افزونه مرورگر بارگذاری نمی‌شود:

• بررسی قالب‌بندی صحیح manifest.json
• مشاهده کنسول مرورگر برای خطاها
• پیروی از دستورالعمل نصب افزونه مطابق مرورگر

مشکلات پروژه چت پایتون:

• نصب بسته 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 برای فرمت یکنواخت
• استفاده از ابزارهای توسعه مرورگر برای اشکال‌زدایی جاوااسکریپت
• نصب افزونه Vue DevTools برای پروژه‌های Vue

ملاحظات عملکرد

• تعداد زیاد فایل‌های ترجمه شده (بیش از ۵۰ زبان) سبب حجم بزرگ کلون کامل می‌شود
• استفاده از کلون سطحی در صورت کار صرفاً با محتوا: git clone --depth 1
• حذف ترجمه‌ها از جستجو هنگام کار با محتوای انگلیسی
• روندهای ساخت در اولین اجرا ممکن است کند باشند (npm install، ساخت Vite)

ملاحظات امنیتی

متغیرهای محیطی

• کلیدهای API نباید در مخزن کامیت شوند
• استفاده از فایل‌های .env (قبلاً در .gitignore قرار دارند)
• مستندسازی متغیرهای محیطی مورد نیاز در README پروژه‌ها

پروژه‌های پایتون

• استفاده از محیط‌های مجازی: python -m venv venv
• نگه داشتن به‌روزرسانی وابستگی‌ها
• توکن‌های GitHub باید حداقل مجوزهای لازم را داشته باشند

دسترسی به مدل‌های GitHub

• توکن‌های دسترسی شخصی (PAT) برای دسترسی به مدل‌ها لازم است
• توکن‌ها باید در متغیرهای محیطی ذخیره شوند
• هرگز توکن‌ها یا اطلاعات حساس را کامیت نکنید

یادداشت‌های اضافی

مخاطبان هدف

• مبتدیان کامل در توسعه وب
• دانش‌آموزان و یادگیرندگان خودآموز
• معلمانی که برنامه درسی را در کلاس تدریس می‌کنند
• محتوا به گونه‌ای طراحی شده که دسترسی‌پذیر و به صورت تدریجی مهارت‌ها را می‌سازد

فلسفه آموزشی

• رویکرد یادگیری مبتنی بر پروژه
• بررسی مکرر دانش (آزمون‌ها)
• تمرین‌های عملی برنامه‌نویسی
• مثال‌های کاربردی در دنیای واقعی
• تأکید بر مبانی پیش از فریمورک‌ها

نگهداری مخزن

• جامعه فعالی از یادگیرندگان و مشارکت‌کنندگان
• به‌روزرسانی منظم وابستگی‌ها و محتوا
• نظارت بر بحث‌ها و مسائل توسط نگه‌داران
• بروزرسانی ترجمه‌ها به‌طور خودکار توسط GitHub Actions

منابع مرتبط

• ماژول‌های Microsoft Learn
• مرکز دانش‌آموزان Student Hub
• گیت‌هاب کوپایلوت 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 - پروژه دستیار چت AI

ساختار مونو رپو

اگرچه این مخزن یک مونو رپوی سنتی نیست، شامل چند پروژه مستقل است:

• هر درس خودکفا است
• پروژه‌ها وابستگی مشترک ندارند
• می‌توان روی پروژه‌های فردی بدون تأثیر بر دیگران کار کرد
• کلون کل مخزن برای تجربه کامل برنامه درسی لازم است

---

سلب مسئولیت:
این سند با استفاده از سرویس ترجمه هوش مصنوعی Co-op Translator ترجمه شده است. در حالی که ما برای دقت تلاش می‌کنیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا عدم دقت‌هایی باشند. سند اصلی به زبان بومی خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما مسئول هیچ گونه سوءتفاهم یا تفسیر نادرست ناشی از استفاده از این ترجمه نیستیم.