<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "a362efd06d64d4134a0cfe8515a86d34",
  "translation_date": "2025-10-03T11:15:55+00:00",
  "source_file": "AGENTS.md",
  "language_code": "ur"
}
-->
# AGENTS.md

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

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

### اہم اجزاء

- **تعلیمی مواد**: 24 منظم اسباق جو پروجیکٹ پر مبنی ماڈیولز میں ترتیب دیے گئے ہیں
- **عملی پروجیکٹس**: Terrarium، Typing Game، Browser Extension، Space Game، Banking App، Code Editor، اور AI Chat Assistant
- **انٹرایکٹو کوئزز**: 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
```

### Quiz App سیٹ اپ (Vue 3 + Vite)

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

### Bank Project API (Node.js + Express)

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

### Browser Extension پروجیکٹس

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

### Space Game پروجیکٹس

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

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

```bash
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. شراکت کے رہنما اصولوں کے مطابق پل ریکویسٹ جمع کروائیں

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

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

### لائیو ترقی

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

## جانچ کی ہدایات

### Quiz App جانچ

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

### Bank API جانچ

```bash
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 ہے
- مارک ڈاؤن لنکس کی تصدیق کریں
- کوڈ کی مثالوں کو براؤزر یا Node.js میں جانچیں
- ترجمے کی ساخت کو درست رکھیں

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

### جاوا اسکرپٹ

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

### HTML/CSS

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

### Python

- PEP 8 اسٹائل کے رہنما اصول
- واضح، تعلیمی کوڈ کی مثالیں
- جہاں سیکھنے کے لیے مددگار ہو، ٹائپ ہنٹس شامل کریں

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

- واضح ہیڈنگ کی درجہ بندی
- زبان کی وضاحت کے ساتھ کوڈ بلاکس
- اضافی وسائل کے لنکس
- `images/` ڈائریکٹریز میں اسکرین شاٹس اور تصاویر
- تصاویر کے لیے متبادل متن برائے رسائی

### فائل تنظیم

- اسباق کو ترتیب وار نمبر دیا گیا (1-getting-started-lessons، 2-js-basics، وغیرہ)
- ہر پروجیکٹ میں `solution/` اور اکثر `start/` یا `your-work/` ڈائریکٹریز ہوتی ہیں
- تصاویر سبق کے مخصوص `images/` فولڈرز میں محفوظ کی جاتی ہیں
- ترجمے `translations/{language-code}/` ساخت میں

## تعمیر اور تعیناتی

### Quiz App تعیناتی (Azure Static Web Apps)

quiz-app Azure Static Web Apps تعیناتی کے لیے کنفیگر ہے:

```bash
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 جنریشن

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

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

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

### پروجیکٹ مخصوص تعمیرات

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

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

### عنوان کی شکل

تبدیلی کے علاقے کی وضاحت کرنے والے واضح، وضاحتی عنوانات استعمال کریں:
- `[Quiz-app] Add new quiz for lesson X`
- `[Lesson-3] Fix typo in terrarium project`
- `[Translation] Add Spanish translation for lesson 5`
- `[Docs] Update setup instructions`

### مطلوبہ چیک

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

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

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

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

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

### شراکت کی ضروریات

- Microsoft 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": "..."
}
-->
```

## ڈیبگنگ اور خرابیوں کا ازالہ

### عام مسائل

**Quiz app شروع نہیں ہو رہا**:
- Node.js ورژن چیک کریں (v14+ تجویز کردہ)
- `node_modules` اور `package-lock.json` حذف کریں، دوبارہ `npm install` چلائیں
- پورٹ کے تنازعات چیک کریں (ڈیفالٹ: Vite پورٹ 5173 استعمال کرتا ہے)

**API سرور شروع نہیں ہو رہا**:
- Node.js ورژن کم از کم ضروریات کو پورا کرتا ہے (node >=10)
- چیک کریں کہ پورٹ پہلے سے استعمال میں ہے
- تمام انحصارات `npm install` کے ساتھ انسٹال کریں

**براؤزر ایکسٹینشن لوڈ نہیں ہو رہا**:
- تصدیق کریں کہ manifest.json صحیح طور پر فارمیٹ کیا گیا ہے
- براؤزر کنسول میں غلطیوں کو چیک کریں
- براؤزر مخصوص ایکسٹینشن انسٹالیشن ہدایات پر عمل کریں

**Python chat پروجیکٹ کے مسائل**:
- تصدیق کریں کہ 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+ زبانیں) کا مطلب ہے کہ مکمل کلونز بڑے ہیں
- اگر صرف مواد پر کام کر رہے ہیں تو شالو کلون استعمال کریں: `git clone --depth 1`
- انگریزی مواد پر کام کرتے وقت ترجمے کو تلاش سے خارج کریں
- پہلی بار چلانے پر تعمیراتی عمل سست ہو سکتا ہے (npm install، Vite build)

## سیکیورٹی تحفظات

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

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

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

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

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

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

## اضافی نوٹس

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

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

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

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

### ذخیرہ کی دیکھ بھال

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

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

- [Microsoft Learn modules](https://docs.microsoft.com/learn/)
- [Student Hub resources](https://docs.microsoft.com/learn/student-hub/)
- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) سیکھنے والوں کے لیے تجویز کردہ
- اضافی کورسز: Generative AI، Data Science، ML، 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` - AI چیٹ اسسٹنٹ پروجیکٹ

### Monorepo ساخت

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

---

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