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

AGENTS.md

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

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

اجزای کلیدی

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

API پروژه بانکی (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)

cd 9-chat-project/solution/backend/python
pip install openai
# Set GITHUB_TOKEN environment variable
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 را در ریشه اجرا کنید (پورت ۳۰۰۰)
• اپلیکیشن آزمون: دستور npm run dev را در دایرکتوری quiz-app اجرا کنید
• پروژه‌ها: از افزونه Live Server در VS Code برای پروژه‌های HTML استفاده کنید
• پروژه‌های API: دستور npm start را در دایرکتوری‌های API مربوطه اجرا کنید

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

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

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

آزمایش API بانکی

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 آزمایش کنید
• اطمینان حاصل کنید که ترجمه‌ها ساختار مناسب را حفظ کرده‌اند

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

جاوااسکریپت

• استفاده از سینتکس مدرن 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)

اپلیکیشن آزمون برای استقرار در 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 بسته‌های تولیدی ایجاد می‌کند
• پروژه‌های استاتیک: مرحله ساخت ندارند، فایل‌ها را مستقیماً ارائه دهید

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

قالب عنوان

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

• [Quiz-app] افزودن آزمون جدید برای درس X
• [Lesson-3] اصلاح اشتباه تایپی در پروژه terrarium
• [Translation] افزودن ترجمه اسپانیایی برای درس ۵
• [Docs] به‌روزرسانی دستورالعمل‌های راه‌اندازی

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

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

1. کیفیت کد:

   • دستور npm run lint را در دایرکتوری‌های پروژه‌های تحت تأثیر اجرا کنید
   • تمام خطاها و هشدارهای linting را اصلاح کنید

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

   • دستور npm run build را در صورت لزوم اجرا کنید
   • اطمینان حاصل کنید که هیچ خطای ساخت وجود ندارد

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

   • تمام لینک‌های markdown را آزمایش کنید
   • اطمینان حاصل کنید که ارجاعات تصاویر کار می‌کنند

4. بررسی محتوا:

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

الزامات مشارکت

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

فرآیند بررسی

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

سیستم ترجمه

ترجمه خودکار

• از GitHub Actions با جریان کاری 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 از پورت 5173 استفاده می‌کند)

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

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

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

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

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

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

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

پروژه‌های Python

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

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

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

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

مخاطبان هدف

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

فلسفه آموزشی

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

نگهداری مخزن

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

منابع مرتبط

• ماژول‌های Microsoft Learn
• منابع Student Hub
• GitHub Copilot برای یادگیرندگان توصیه می‌شود
• دوره‌های اضافی: هوش مصنوعی مولد، علم داده، یادگیری ماشین، برنامه‌های IoT در دسترس هستند

کار با پروژه‌های خاص

برای دستورالعمل‌های دقیق در مورد پروژه‌های فردی، به فایل‌های 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

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

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

---

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