ur

Imported from Xerkara/Web-Dev-Sandbox (translations/ur/AGENTS.md). Install upstream with npx skills add Xerkara/Web-Dev-Sandbox --skill ur. Copyright stays with the author.

AGENTS.md

پروجیکٹ کا جائزہ

یہ ابتدائیوں کو ویب ڈویلپمنٹ کے بنیادی اصول سکھانے کے لیے ایک تعلیمی نصاب کا مخزن ہے۔ نصاب 12 ہفتوں پر محیط ایک جامع کورس ہے جو Microsoft Cloud Advocates نے تیار کیا ہے، جس میں جاوا اسکرپٹ، CSS، اور HTML پر مشتمل 24 عملی اسباق شامل ہیں۔

کلیدی اجزاء

• تعلیمی مواد: 24 منظم اسباق جو پراجیکٹ پر مبنی ماڈیولز میں منظم ہیں
• عملی پراجیکٹس: ٹیریریم، ٹائپنگ گیم، براؤزر ایکسٹینشن، اسپیس گیم، بینکنگ ایپ، کوڈ ایڈیٹر، اور AI چیٹ اسسٹنٹ
• انٹرایکٹو کوئزز: 48 کوئزز جن میں ہر ایک میں 3 سوالات ہوتے ہیں (سبق سے پہلے/بعد کی تشخیص)
• کثیراللسانی معاونت: GitHub Actions کے ذریعے 50+ زبانوں میں خودکار ترجمے
• ٹیکنالوجیز: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (AI پراجیکٹس کے لیے)

فن تعمیر

• سبق پر مبنی تعلیمی مخزن
• ہر سبق فولڈر میں 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 کھولیں یا Live Server استعمال کریں

چیٹ پراجیکٹ (Python بیک اینڈ)

cd 9-chat-project/solution/backend/python
pip install openai
# GITHUB_TOKEN ماحولیاتی متغیر مقرر کریں
python api.py

ترقیاتی ورک فلو

مواد کے شراکت داروں کے لیے

1. اپنا GitHub اکاؤنٹ میں مخزن کو فورک کریں
2. اپنے فورک کو لوکل کلون کریں
3. اپنی تبدیلیوں کے لیے نئی برانچ بنائیں
4. سبق کے مواد یا کوڈ مثالوں میں تبدیلی کریں
5. متعلقہ پراجیکٹ ڈائریکٹریز میں کوڈ کی تبدیلیاں ٹیسٹ کریں
6. شراکت کے رہنما خطوط کے مطابق پل ریکویسٹ جمع کروائیں

سیکھنے والوں کے لیے

1. مخزن کو فورک یا کلون کریں
2. مرحلہ وار سبق کی ڈائریکٹریز پر جائیں
3. ہر سبق کے README فائلز پڑھیں
4. سبق سے پہلے کی کوئزز مکمل کریں https://ff-quizzes.netlify.app/web/
5. سبق کی فولڈرز میں کوڈ کی مثالوں پر کام کریں
6. اسائنمنٹس اور چیلنجز مکمل کریں
7. سبق کے بعد کی کوئزز دیں

لائیو ڈیولپمنٹ

• دستاویزات: روٹ میں docsify serve چلائیں (پورٹ 3000)
• کوئز ایپ: quiz-app ڈائریکٹری میں npm run dev چلائیں
• پراجیکٹس: HTML پراجیکٹس کے لیے VS Code Live Server ایکسٹینشن استعمال کریں
• API پراجیکٹس: متعلقہ API ڈائریکٹریز میں npm start چلائیں

ٹیسٹنگ کی ہدایات

کوئز ایپ ٹیسٹنگ

cd quiz-app
npm run lint       # کوڈ اسٹائل کے مسائل کی جانچ کریں
npm run build      # تصدیق کریں کہ بلڈ کامیاب ہو گیا ہے

بینک API ٹیسٹنگ

cd 7-bank-project/api
npm run lint       # کوڈ کے انداز کے مسائل چیک کریں
node server.js     # تصدیق کریں کہ سرور بغیر کسی خرابی کے شروع ہوتا ہے

عمومی ٹیسٹنگ طریقہ کار

• یہ ایک تعلیمی مخزن ہے جس میں جامع خودکار ٹیسٹ شامل نہیں
• دستی ٹیسٹنگ پر توجہ مرکوز ہے:
  • کوڈ مثالیں بغیر غلطی کے چلتی ہیں
  • دستاویزات میں لنکس درست کام کرتے ہیں
  • پراجیکٹ بلڈ کامیابی سے مکمل ہوتے ہیں
  • مثالیں بہترین طریقے کار کی پیروی کرتی ہیں

پیشگی چیک

• package.json والے فولڈرز میں npm run lint چلائیں
• مارک ڈاؤن لنکس کی درستگی کی تصدیق کریں
• کوڈ مثالوں کو براؤزر یا Node.js میں ٹیسٹ کریں
• یقینی بنائیں کہ تراجم ڈھانچے کو صحیح طریقے سے برقرار رکھتے ہیں

کوڈ اسٹائل کے رہنما اصول

جاوا اسکرپٹ

• جدید ES6+ نحو استعمال کریں
• پراجیکٹس میں مہیا کردہ معیاری ESLint کنفیگریشن پر عمل کریں
• تعلیمی وضاحت کے لیے معنی خیز متغیر اور فنکشن نام استعمال کریں
• سیکھنے والوں کے لیے تصورات کی وضاحت کے لیے تبصرے شامل کریں
• جہاں کنفیگر کیا گیا ہو Prettier سے فارمیٹ کریں

HTML/CSS

• معنوی HTML5 اجزاء
• ریسپانسیو ڈیزائن کے اصول
• واضح کلاس نامی کنونشنز
• سیکھنے والوں کے لیے CSS تکنیک کی وضاحت کے تبصرے

پائتھون

• PEP 8 اسٹائل گائیڈ لائنز
• واضح، تعلیمی کوڈ مثالیں
• سیکھنے کے لیے جہاں مفید ہو ٹائپ ہنٹس

مارک ڈاؤن دستاویزات

• واضح ہیڈنگ ہائیرارکی
• زبان کی وضاحت کے ساتھ کوڈ بلاکس
• اضافی وسائل کے لنکس
• images/ ڈائریکٹریز میں اسکرین شاٹس اور تصاویر
• معذوری کے لیے تصاویر کے لیے Alt متن

فائل تنظیم

• اسباق متسلسل نمبرات کے ساتھ (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      # فولڈر dist/ بناتا ہے
# مین پر پش کرنے پر GitHub Actions ورک فلو کے ذریعے تعینات کرتا ہے

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               # docs سے PDF بنائیں

Docsify دستاویزات

npm install -g docsify-cli    # ڈاکسفائی کو عالمی طور پر انسٹال کریں
docsify serve                 # لوکل ہوسٹ:3000 پر سروس دیں

پراجیکٹ مخصوص بلڈز

ہر پراجیکٹ ڈائریکٹری کا اپنا بلڈ عمل ہو سکتا ہے:

• Vue پراجیکٹس: npm run build سے پروڈکشن بنڈلز بنتے ہیں
• Static پراجیکٹس: کوئی بلڈ مرحلہ نہیں، فائلیں براہ راست سرف کی جاتی ہیں

پل ریکویسٹ رہنما خطوط

عنوان کی شکل

صاف، وضاحتی عنوانات استعمال کریں جو تبدیلی کے علاقے کی نشاندہی کرتے ہوں:

• [Quiz-app] سبق X کے لیے نیا کوئز شامل کریں
• [Lesson-3] ٹیریریم پراجیکٹ میں ٹائپو کی اصلاح کریں
• [Translation] سبق 5 کے لیے ہسپانوی ترجمہ شامل کریں
• [Docs] سیٹ اپ ہدایات اپ ڈیٹ کریں

درکار چیک

PR جمع کروانے سے پہلے:

1. کوڈ معیار:

   • متاثرہ پراجیکٹ ڈائریکٹریز میں npm run lint چلائیں
   • تمام lint غلطیاں اور وارننگز درست کریں

2. بلڈ توثیق:

   • اگر قابل اطلاق ہو تو npm run build چلائیں
   • یقینی بنائیں کہ کوئی بلڈ غلطی نہ ہو

3. لنک ویریفیکیشن:

   • تمام مارک ڈاؤن لنکس کی جانچ کریں
   • امیج حوالہ جات کی تصدیق کریں

4. مواد کا جائزہ:

   • املا اور گرامر کی جانچ کریں
   • کوڈ مثالیں درست اور تعلیمی ہوں
   • ترجمے اصل معنی برقرار رکھیں

تعاون کی ضروریات

• Microsoft CLA سے اتفاق کریں (پہلے PR پر خودکار چیک)
• Microsoft Open Source Code of Conduct کی پیروی کریں
• تفصیلی رہنما خطوط کے لیے CONTRIBUTING.md دیکھیں
• اگر قابل اطلاق ہو تو PR کی وضاحت میں مسئلے کے نمبر حوالہ کریں

جائزہ لینے کا عمل

• PRs کا جائزہ مینٹیینرز اور کمیونٹی کرتے ہیں
• تعلیمی وضاحت کو ترجیح دی جاتی ہے
• کوڈ مثالیں موجودہ بہترین طریقوں کی پیروی کریں
• تراجم کی درستگی اور ثقافتی مطابقت کی جانچ کی جاتی ہے

ترجمہ کا نظام

خودکار ترجمہ

• 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 استعمال کرتا ہے)

API سرور شروع نہیں ہوتا:

• Node.js ورژن کم از کم node >=10 ہونا چاہیے
• چیک کریں کہ پورٹ استعمال میں نہ ہو
• تمام انحصارات npm install سے انسٹال ہوں

براؤزر ایکسٹینشن نہیں چلتی:

• manifest.json کی درست فارمیٹنگ چیک کریں
• براؤزر کنسول میں غلطیاں دیکھیں
• براؤزر مخصوص ایکسٹینشن انسٹالیشن ہدایات پر عمل کریں

Python چیٹ پراجیکٹ کے مسائل:

• OpenAI پیکج انسٹال کریں: pip install openai
• GITHUB_TOKEN ماحول کی ویریبل سیٹ ہے
• GitHub Models تک رسائی کے اجازت نامے چیک کریں

Docsify دستاویزات سرور نہیں کر رہا:

• docsify-cli گلوبلی انسٹال کریں: npm install -g docsify-cli
• مخزن کی روٹ ڈائریکٹری سے چلائیں
• چیک کریں کہ docs/_sidebar.md موجود ہو

ترقیاتی ماحول کے ٹپس

• HTML پراجیکٹس کے لیے VS Code میں Live Server ایکسٹینشن استعمال کریں
• ESLint اور Prettier ایکسٹینشن انسٹال کریں تاکہ فارمیٹنگ یکساں رہے
• جاوا اسکرپٹ کی خرابیوں کے لیے براؤزر DevTools استعمال کریں
• Vue پراجیکٹس کے لیے Vue DevTools براؤزر ایکسٹینشن انسٹال کریں

کارکردگی کے امور

• ترجمہ شدہ فائلوں کی بڑی تعداد (50+ زبانیں) کلوننگ کو بڑا بناتی ہے
• صرف مواد پر کام کے لیے shallow clone استعمال کریں: git clone --depth 1
• انگریزی مواد پر کام کے دوران ترجمہ شدہ فائلوں کو تلاش سے خارج کریں
• بلڈ عمل پہلے چلاوے پر سست ہو سکتا ہے (npm install، Vite build)

سیکیورٹی کے امور

ماحول کی ویریبلز

• API کیز کبھی بھی مخزن میں جمع نہ کریں
• .env فائلز کا استعمال کریں (جو پہلے ہی .gitignore میں ہیں)
• درکار ماحول کی ویریبلز پراجیکٹ READMEs میں دستاویزی کریں

پائتھون پراجیکٹس

• ورچوئل ماحول استعمال کریں: python -m venv venv
• انحصارات کو بروقت اپڈیٹ رکھیں
• GitHub ٹوکنز کو کم از کم ضروری اجازتیں دینی چاہئیں

GitHub Models تک رسائی

• GitHub Models کے لیے Personal Access Tokens (PAT) ضروری ہیں
• ٹوکنز کو ماحول کی ویریبلز کے طور پر محفوظ کریں
• ٹوکنز یا اسناد کو کبھی بھی کمیٹ نہ کریں

اضافی نوٹس

ہدف سامعین

• ویب ڈویلپمنٹ کے مکمل نو آموز
• طلباء اور خود سیکھنے والے
• اساتذہ جو نصاب کو کلاس رومز میں استعمال کرتے ہیں
• مواد قابل رسائی اور بتدریج مہارت سازی کے لیے ڈیزائن کیا گیا ہے

تعلیمی فلسفہ

• پراجیکٹ پر مبنی سیکھنے کا طریقہ
• بار بار علم کی جانچ (کوئزز)
• عملی کوڈنگ مشقیں
• حقیقی دنیا کی ایپلیکیشن کی مثالیں
• فریم ورکس سے پہلے بنیادی اصولوں پر توجہ

مخزن کی دیکھ بھال

• سیکھنے والوں اور تعاون کنندگان کی فعال کمیونٹی
• انحصارات اور مواد کی باقاعدہ اپ ڈیٹس
• مسائل اور مباحثے مینٹیینرز کی نگرانی میں
• ترجمہ کی اپ ڈیٹس GitHub Actions کے ذریعے خودکار

متعلقہ وسائل

• Microsoft Learn modules
• Student Hub resources
• GitHub Copilot سیکھنے والوں کے لیے تجویز کردہ
• اضافی کورسز: جنریٹو AI، ڈیٹا سائنس، ML، IoT نصاب دستیاب ہیں

مخصوص پراجیکٹس کے ساتھ کام

انفرادی پراجیکٹس کی تفصیلی ہدایات کے لیے، درج ذیل README فائلوں کا حوالہ دیں:

• quiz-app/README.md - Vue 3 کوئز ایپلیکیشن
• 7-bank-project/README.md - تصدیق کے ساتھ بینکنگ ایپلیکیشن
• 5-browser-extension/README.md - براؤزر ایکسٹینشن ڈیولپمنٹ
• 6-space-game/README.md - کینوس پر مبنی گیم ڈیولپمنٹ
• 9-chat-project/README.md - AI چیٹ اسسٹنٹ پراجیکٹ

مونو رپو ساخت

اگرچہ یہ روایتی مونو رپو نہیں ہے، یہ مخزن متعدد آزاد پراجیکٹس پر مشتمل ہے:

• ہر سبق خود مختار ہے
• پراجیکٹس انحصارات شیئر نہیں کرتے
• بغیر دوسرے پراجیکٹس کو متاثر کیے انفرادی پراجیکٹس پر کام کریں
• پورے نصاب کے تجربے کے لیے پورا مخزن کلون کریں

خبردار:
اس دستاویز کا ترجمہ AI ترجمہ سروس Co-op Translator کے ذریعے کیا گیا ہے۔ اگرچہ ہم درستگی کے لیے کوشاں ہیں، براہ کرم آگاہ رہیں کہ خودکار تراجم میں غلطیاں یا عدم صحیحیت ہو سکتی ہے۔ اصل دستاویز اپنی اصلی زبان میں معتبر ماخذ سمجھی جائے گی۔ اہم معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم پر عائد نہیں ہوتی۔