# AGENTS.md

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

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

### کلیدی اجزاء

- **تعلیمی مواد**: 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 کے طور پر دستیاب ہیں

## سیٹ اپ کمانڈز

یہ ذخیرہ بنیادی طور پر تعلیمی مواد کے استعمال کے لیے ہے۔ مخصوص پروجیکٹس پر کام کرنے کے لیے:

### مرکزی ذخیرہ سیٹ اپ

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

### کوئز ایپ سیٹ اپ (Vue 3 + Vite)

```bash
cd quiz-app
npm install
npm run dev        # ڈیولپمنٹ سرور شروع کریں
npm run build      # پروڈکشن کے لیے تیار کریں
npm run lint       # ESLint چلائیں
```

### بینک پروجیکٹ API (Node.js + Express)

```bash
cd 7-bank-project/api
npm install
npm start          # API سرور شروع کریں
npm run lint       # ESLint چلائیں
npm run format     # Prettier کے ساتھ فارمیٹ کریں
```

### براؤزر ایکسٹینشن پروجیکٹس

```bash
cd 5-browser-extension/solution
npm install
# مخصوص براؤزر کے لیے ایکسٹینشن لوڈ کرنے کی ہدایات پر عمل کریں
```

### اسپیس گیم پروجیکٹس

```bash
cd 6-space-game/solution
npm install
# براؤزر میں index.html کھولیں یا Live Server استعمال کریں
```

### چیٹ پروجیکٹ (Python Backend)

```bash
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` چلائیں

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

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

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

### بینک API ٹیسٹنگ

```bash
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 تعیناتی کے لیے کنفیگر ہے:

```bash
cd quiz-app
npm run build      # dist/ فولڈر بناتا ہے
# مرکزی شاخ پر push کرنے پر GitHub Actions ورک فلو کے ذریعے تعینات کرتا ہے
```

Azure Static Web Apps کی ترتیب:
- **ایپ لوکیشن**: `/quiz-app`
- **آؤٹ پٹ لوکیشن**: `dist`
- **ورک فلو**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`

### دستاویزات PDF جنریشن

```bash
npm install                    # docsify-to-pdf انسٹال کریں
npm run convert               # docs سے PDF بنائیں
```

### Docsify دستاویزات

```bash
npm install -g docsify-cli    # دستاویزات کو عالمی سطح پر انسٹال کریں
docsify serve                 # لوکل ہوسٹ:3000 پر خدمت کریں
```

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

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

## پل ریکویسٹ کی رہنمائی

### عنوان کی صورت

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

### ضروری چیکس

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

1. **کوڈ کوالٹی**:
   - متاثرہ پروجیکٹ فولڈرز میں `npm run lint` چلائیں
   - تمام لنٹنگ کی غلطیاں اور وارننگز درست کریں

2. **بلڈ کی تصدیق**:
   - اگر قابل اطلاق ہو تو `npm run build` چلائیں
   - یقینی بنائیں کہ کوئی بلڈ ایرر نہ ہو

3. **لنک کی توثیق**:
   - تمام مارک ڈاؤن لنکس ٹیسٹ کریں
   - تصاویر کے ریفرنس درست ہوں

4. **مواد کا جائزہ**:
   - ہجے اور گرائمر کی جانچ پڑتال کریں
   - کوڈ کی مثالیں درست اور تعلیمی ہوں
   - ترجمے اصل معنی کو برقرار رکھیں

### تعاون کی شرائط

- مائیکروسافٹ CLA سے اتفاق کریں (پہلے PR پر خودکار چیک)
- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) کی پیروی کریں
- تفصیلی رہنما خطوط کے لیے [CONTRIBUTING.md](./CONTRIBUTING.md) دیکھیں
- اگر قابل اطلاق ہو تو PR وضاحت میں ایشو نمبرز کا حوالہ دیں

### جائزے کا عمل

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

## ترجمہ کا نظام

### خودکار ترجمہ

- GitHub Actions کو co-op-translator ورک فلو کے ساتھ استعمال کرتا ہے
- 50+ زبانوں میں خودکار طور پر ترجمہ کرتا ہے
- ماخذ فائلیں مرکزی ڈائریکٹریز میں ہیں
- ترجمہ شدہ فائلیں `translations/{language-code}/` ڈائریکٹریز میں

### دستی ترجمہ کی بہتریاں شامل کرنا

1. `translations/{language-code}/` میں فائل تلاش کریں
2. ساخت برقرار رکھتے ہوئے بہتریاں کریں
3. یقینی بنائیں کہ کوڈ کی مثالیں کارآمد رہیں
4. کسی مقامی کوئز مواد کو ٹیسٹ کریں

### ترجمہ مٹاداتا

ترجمہ شدہ فائلوں میں مٹاداتا ہیڈر شامل ہوتا ہے:
```markdown
<!--
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)
- چیک کریں کہ پورٹ پہلے سے استعمال میں نہ ہو
- یقینی بنائیں کہ تمام dependencies نصب ہیں `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 ایکسٹینشن انسٹال کریں
- JavaScript کی ڈیبگنگ کے لیے براؤزر DevTools استعمال کریں
- Vue پروجیکٹس کے لیے Vue DevTools براؤزر ایکسٹینشن انسٹال کریں

### کارکردگی کے پہلو

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

## سیکیورٹی کے پہلو

### ماحول کے متغیرات

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

### Python پروجیکٹس

- ورچوئل ماحول استعمال کریں: `python -m venv venv`
- dependencies کو اپ ٹو ڈیٹ رکھیں
- GitHub ٹوکنز کو کم سے کم درکار اجازتوں کے ساتھ رکھیں

### GitHub Models کی رسائی

- GitHub Models کے لیے ذاتی رسائی کے ٹوکن (PAT) ضروری ہیں
- ٹوکنز کو ماحول کے متغیرات کے طور پر محفوظ کریں
- ٹوکنز یا اسناد کو کبھی جمع نہ کریں

## اضافی نوٹ

### ہدف سامعین

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

### تعلیمی فلسفہ

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

### ذخیرہ کا انتظام

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

### متعلقہ وسائل

- [Microsoft Learn ماڈیولز](https://docs.microsoft.com/learn/)
- [Student Hub کے وسائل](https://docs.microsoft.com/learn/student-hub/)
- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=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 چیٹ اسسٹنٹ پروجیکٹ

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

اگرچہ یہ روایتی monorepo نہیں ہے، مگر اس ذخیرے میں متعدد آزاد پروجیکٹس شامل ہیں:
- ہر سبق خود سے مکمل ہے
- پروجیکٹس ایک دوسرے کی dependencies شیئر نہیں کرتے
- ایک ساتھ دوسرے پروجیکٹس کو متاثر کیے بغیر الگ الگ کام کریں
- پورے نصاب کے تجربے کے لیے مکمل ذخیرہ کلون کریں

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**دھرنا**:  
یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ اگرچه ہم درستگی کے لیے کوشاں ہیں، براہ کرم نوٹ کریں کہ خودکار ترجموں میں غلطیاں یا عدم درستگیاں ہو سکتی ہیں۔ اصل دستاویز اپنی مادری زبان میں ہی مستند ماخذ سمجھی جانی چاہیے۔ اہم معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم پر نہیں ہوگی۔
<!-- CO-OP TRANSLATOR DISCLAIMER END -->