AGENTS.md

1# AGENTS.md
2 
3## پروجیکٹ کا جائزہ
4 
5یہ ویب ڈیولپمنٹ کے بنیادی اصولوں کی تعلیم کے لیے ایک تعلیمی نصاب کا ذخیرہ ہے جو مبتدیوں کے لیے ہے۔ یہ نصاب مائیکروسافٹ کلاؤڈ ایڈووکیٹس کے ذریعہ تیار کردہ ایک جامع 12 ہفتوں کا کورس ہے، جس میں 24 عملی اسباق شامل ہیں جو جاوا اسکرپٹ، CSS، اور HTML کا احاطہ کرتے ہیں۔
6 
7### کلیدی اجزاء
8 
9- **تعلیمی مواد**: 24 منظم اسباق جو پروجیکٹ پر مبنی ماڈیولز میں ترتیب دیے گئے ہیں
10- **عملی پروجیکٹس**: ٹیریریم، ٹائپنگ گیم، براؤزر ایکسٹینشن، اسپیس گیم، بینکنگ ایپ، کوڈ ایڈیٹر، اور AI چیٹ اسسٹنٹ
11- **انٹرایکٹو کوئزز**: 48 کوئزز، ہر ایک میں 3 سوالات (سبق سے پہلے/بعد کے جائزے)
12- **کثیر لسانی معاونت**: GitHub Actions کے ذریعے 50+ زبانوں کے لیے خودکار تراجم
13- **تکنالوجیز**: HTML، CSS، JavaScript، Vue.js 3، Vite، Node.js، Express، Python (AI پروجیکٹس کے لیے)
14 
15### فن تعمیر
16 
17- سبق کی بنیاد پر تعلیمی ذخیرہ
18- ہر سبق فولڈر میں README، کوڈ کے نمونے اور حل شامل ہیں
19- علیحدہ ڈائریکٹریز میں آزاد پروجیکٹس (quiz-app، مختلف سبق کے پروجیکٹس)
20- ترجمہ کا نظام GitHub Actions (co-op-translator) استعمال کرتا ہے
21- دستاویزات Docsify کے ذریعے فراہم کی جاتی ہیں اور PDF کے طور پر دستیاب ہیں
22 
23## سیٹ اپ کمانڈز
24 
25یہ ذخیرہ بنیادی طور پر تعلیمی مواد کے استعمال کے لیے ہے۔ مخصوص پروجیکٹس پر کام کرنے کے لیے:
26 
27### مرکزی ذخیرہ سیٹ اپ
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### کوئز ایپ سیٹ اپ (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # ڈیولپمنٹ سرور شروع کریں
40npm run build      # پروڈکشن کے لیے تیار کریں
41npm run lint       # ESLint چلائیں
42```
43 
44### بینک پروجیکٹ API (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # API سرور شروع کریں
50npm run lint       # ESLint چلائیں
51npm run format     # Prettier کے ساتھ فارمیٹ کریں
52```
53 
54### براؤزر ایکسٹینشن پروجیکٹس
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# مخصوص براؤزر کے لیے ایکسٹینشن لوڈ کرنے کی ہدایات پر عمل کریں
60```
61 
62### اسپیس گیم پروجیکٹس
63 
64```bash
65cd 6-space-game/solution
66npm install
67# براؤزر میں index.html کھولیں یا Live Server استعمال کریں
68```
69 
70### چیٹ پروجیکٹ (Python Backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# GITHUB_TOKEN ماحول کا متغیر سیٹ کریں
76python api.py
77```
78 
79## ترقیاتی ورک فلو
80 
81### مواد فراہم کرنے والوں کے لیے
82 
831. اپنے GitHub اکاؤنٹ میں ذخیرہ کی فورک کریں
842. اپنی فورک کا کلون لوکل کریں
853. اپنی تبدیلیوں کے لیے نئی برانچ بنائیں
864. سبق کے مواد یا کوڈ کی مثالوں میں تبدیلی کریں
875. متعلقہ پروجیکٹ ڈائریکٹریز میں کوڈ کی تبدیلیوں کا ٹیسٹ کریں
886. تعاون کی رہنمائی کے مطابق پل ریکویسٹ جمع کروائیں
89 
90### سیکھنے والوں کے لیے
91 
921. ذخیرہ کو فورک یا کلون کریں
932. سبق کی ڈائریکٹریز میں تسلسل کے ساتھ جائیں
943. ہر سبق کی README فائلز پڑھیں
954. سبق سے پہلے کے کوئزز پورے کریں https://ff-quizzes.netlify.app/web/
965. سبق کے فولڈرز میں کوڈ کی مثالوں پر کام کریں
976. تفویضات اور چیلنجز مکمل کریں
987. سبق کے بعد کے کوئزز لیں
99 
100### لائیو ترقی
101 
102- **دستاویزات**: روٹ میں `docsify serve` چلائیں (پورٹ 3000)
103- **کوئز ایپ**: `quiz-app` ڈائریکٹری میں `npm run dev` چلائیں
104- **پروجیکٹس**: HTML پروجیکٹس کے لیے VS Code Live Server ایکسٹینشن استعمال کریں
105- **API پروجیکٹس**: متعلقہ API فولڈرز میں `npm start` چلائیں
106 
107## ٹیسٹنگ کی ہدایات
108 
109### کوئز ایپ ٹیسٹنگ
110 
111```bash
112cd quiz-app
113npm run lint       # کوڈ کے انداز کے مسائل کی جانچ کریں
114npm run build      # تعمیری کامیابی کی تصدیق کریں
115```
116 
117### بینک API ٹیسٹنگ
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # کوڈ کی طرز کے مسائل کی جانچ کریں
122node server.js     # تصدیق کریں کہ سرور بغیر کسی غلطی کے شروع ہوتا ہے
123```
124 
125### عمومی ٹیسٹنگ کا طریقہ کار
126 
127- یہ ایک تعلیمی ذخیرہ ہے جس میں مکمل خودکار ٹیسٹ نہیں ہیں
128- دستی ٹیسٹنگ پر توجہ مرکوز ہے:
129  - کوڈ کی مثالیں بغیر غلطی کے چلیں
130  - دستاویزات میں لنکس صحیح کام کریں
131  - پروجیکٹ کی تعمیر کامیابی سے مکمل ہو
132  - مثالیں بہترین طریقے کار کی پیروی کریں
133 
134### پیشگی جانچ پڑتال
135 
136- وہ فولڈرز جہاں package.json ہو وہاں `npm run lint` چلائیں
137- مارک ڈاؤن لنکس کی درستگی چیک کریں
138- کوڈ کی مثالوں کو براؤزر یا Node.js میں ٹیسٹ کریں
139- یقینی بنائیں کہ ترجمے صحیح ساخت برقرار رکھتے ہیں
140 
141## کوڈ اسٹائل کی ہدایات
142 
143### جاوا اسکرپٹ
144 
145- جدید ES6+ نحو استعمال کریں
146- پروجیکٹس میں فراہم کردہ معیاری ESLint کنفیگریشن استعمال کریں
147- تعلیمی وضاحت کے لیے بامعنی متغیر اور فنکشن کے نام رکھیں
148- مفہوم وضاحت کے لیے تبصرے شامل کریں
149- جہاں کنفیگر کیا گیا ہو وہاں Prettier سے فارمیٹنگ کریں
150 
151### HTML/CSS
152 
153- معنوی HTML5 عناصر استعمال کریں
154- جامع ریسپونسیو ڈیزائن اصول
155- واضح کلاس ناموں کے اصول
156- CSS تکنیک کی وضاحت کے لیے تبصرے
157 
158### پائتھن
159 
160- PEP 8 اسٹائل گائیڈ لائنز
161- واضح، تعلیمی کوڈ کی مثالیں
162- جہاں مددگار ہو وہاں ٹائپ ہنٹس
163 
164### مارک ڈاؤن دستاویزات
165 
166- واضح ہیڈنگ ہائیرارکی
167- زبان کی تفصیل کے ساتھ کوڈ بلاکس
168- اضافی وسائل کے لنکس
169- `images/` ڈائریکٹریز میں اسکرین شاٹس اور تصاویر
170- دستیابی کے لیے تصاویر کا alt متن
171 
172### فائل کا انتظام
173 
174- اسباق کی متواتر نمبرنگ (1-getting-started-lessons, 2-js-basics وغیرہ)
175- ہر پروجیکٹ میں `solution/` اور اکثر `start/` یا `your-work/` ڈائریکٹریز
176- تصاویر سبق کی مخصوص `images/` فولڈرز میں محفوظ
177- تراجم `translations/{language-code}/` فولڈرز میں
178 
179## بلڈ اور تعیناتی
180 
181### کوئز ایپ تعیناتی (Azure Static Web Apps)
182 
183کوئز ایپ Azure Static Web Apps تعیناتی کے لیے کنفیگر ہے:
184 
185```bash
186cd quiz-app
187npm run build      # dist/ فولڈر بناتا ہے
188# مرکزی شاخ پر push کرنے پر GitHub Actions ورک فلو کے ذریعے تعینات کرتا ہے
189```
190 
191Azure Static Web Apps کی ترتیب:
192- **ایپ لوکیشن**: `/quiz-app`
193- **آؤٹ پٹ لوکیشن**: `dist`
194- **ورک فلو**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### دستاویزات PDF جنریشن
197 
198```bash
199npm install                    # docsify-to-pdf انسٹال کریں
200npm run convert               # docs سے PDF بنائیں
201```
202 
203### Docsify دستاویزات
204 
205```bash
206npm install -g docsify-cli    # دستاویزات کو عالمی سطح پر انسٹال کریں
207docsify serve                 # لوکل ہوسٹ:3000 پر خدمت کریں
208```
209 
210### پروجیکٹ مخصوص بلڈز
211 
212ہر پروجیکٹ فولڈر میں اپنا بلڈ عمل ہو سکتا ہے:
213- Vue پروجیکٹس: `npm run build` پروڈکشن بنڈلز بناتا ہے
214- سادہ پروجیکٹس: کوئی بلڈ مرحلہ نہیں، فائلز براہ راست فراہم کی جاتی ہیں
215 
216## پل ریکویسٹ کی رہنمائی
217 
218### عنوان کی صورت
219 
220صاف اور وضاحتی عنوانات استعمال کریں جو تبدیلی کے دائرہ کو ظاہر کریں:
221- `[Quiz-app] سبق X کے لیے نیا کوئز شامل کریں`
222- `[Lesson-3] ٹیریریم پروجیکٹ میں ٹائپو درست کریں`
223- `[Translation] سبق 5 کے لیے ہسپانوی ترجمہ شامل کریں`
224- `[Docs] سیٹ اپ ہدایات کو اپ ڈیٹ کریں`
225 
226### ضروری چیکس
227 
228پل ریکویسٹ جمع کرانے سے پہلے:
229 
2301. **کوڈ کوالٹی**:
231   - متاثرہ پروجیکٹ فولڈرز میں `npm run lint` چلائیں
232   - تمام لنٹنگ کی غلطیاں اور وارننگز درست کریں
233 
2342. **بلڈ کی تصدیق**:
235   - اگر قابل اطلاق ہو تو `npm run build` چلائیں
236   - یقینی بنائیں کہ کوئی بلڈ ایرر نہ ہو
237 
2383. **لنک کی توثیق**:
239   - تمام مارک ڈاؤن لنکس ٹیسٹ کریں
240   - تصاویر کے ریفرنس درست ہوں
241 
2424. **مواد کا جائزہ**:
243   - ہجے اور گرائمر کی جانچ پڑتال کریں
244   - کوڈ کی مثالیں درست اور تعلیمی ہوں
245   - ترجمے اصل معنی کو برقرار رکھیں
246 
247### تعاون کی شرائط
248 
249- مائیکروسافٹ CLA سے اتفاق کریں (پہلے PR پر خودکار چیک)
250- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) کی پیروی کریں
251- تفصیلی رہنما خطوط کے لیے [CONTRIBUTING.md](./CONTRIBUTING.md) دیکھیں
252- اگر قابل اطلاق ہو تو PR وضاحت میں ایشو نمبرز کا حوالہ دیں
253 
254### جائزے کا عمل
255 
256- PRs دیکھ بھال کرنے والے اور کمیونٹی کی جانب سے جائزہ لیے جاتے ہیں
257- تعلیمی وضاحت کو ترجیح دی جاتی ہے
258- کوڈ کی مثالیں موجودہ بہترین طریقے کار کی پیروی کریں
259- ترجمے درستگی اور ثقافتی مطابقت کے لیے جائزہ کے تابع ہیں
260 
261## ترجمہ کا نظام
262 
263### خودکار ترجمہ
264 
265- GitHub Actions کو co-op-translator ورک فلو کے ساتھ استعمال کرتا ہے
266- 50+ زبانوں میں خودکار طور پر ترجمہ کرتا ہے
267- ماخذ فائلیں مرکزی ڈائریکٹریز میں ہیں
268- ترجمہ شدہ فائلیں `translations/{language-code}/` ڈائریکٹریز میں
269 
270### دستی ترجمہ کی بہتریاں شامل کرنا
271 
2721. `translations/{language-code}/` میں فائل تلاش کریں
2732. ساخت برقرار رکھتے ہوئے بہتریاں کریں
2743. یقینی بنائیں کہ کوڈ کی مثالیں کارآمد رہیں
2754. کسی مقامی کوئز مواد کو ٹیسٹ کریں
276 
277### ترجمہ مٹاداتا
278 
279ترجمہ شدہ فائلوں میں مٹاداتا ہیڈر شامل ہوتا ہے:
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## ڈیبگنگ اور مسئلہ حل کرنا
293 
294### عام مسائل
295 
296**کوئز ایپ اسٹارٹ نہیں ہوتی**:
297- Node.js ورژن چیک کریں (v14+ تجویز کردہ)
298- `node_modules` اور `package-lock.json` حذف کریں، پھر `npm install` چلائیں
299- پورٹ تنازعہ چیک کریں (ڈیفالٹ: Vite پورٹ 5173 استعمال کرتا ہے)
300 
301**API سرور اسٹارٹ نہیں ہوتا**:
302- کم از کم Node.js ورژن تصدیق کریں (node >=10)
303- چیک کریں کہ پورٹ پہلے سے استعمال میں نہ ہو
304- یقینی بنائیں کہ تمام dependencies نصب ہیں `npm install` کے ذریعے
305 
306**براؤزر ایکسٹینشن لوڈ نہیں ہوتی**:
307- manifest.json کی درست تشکیل چیک کریں
308- براؤزر کے کنسول میں ایررز دیکھیں
309- براؤزر مخصوص ایکسٹینشن انسٹالیشن ہدایات پر عمل کریں
310 
311**Python چیٹ پروجیکٹ کے مسائل**:
312- یقینی بنائیں OpenAI پیکیج نصب ہے: `pip install openai`
313- GITHUB_TOKEN ماحول کا متغیر سیٹ ہے
314- GitHub Models کی رسائی کی اجازت چیک کریں
315 
316**Docsify دستاویزات فراہم نہیں کر رہا**:
317- docsify-cli گلوبلی انسٹال کریں: `npm install -g docsify-cli`
318- ذخیرہ کی روٹ ڈائریکٹری سے چلائیں
319- چیک کریں کہ `docs/_sidebar.md` موجود ہے
320 
321### ترقیاتی ماحول کی تجاویز
322 
323- HTML پروجیکٹس کے لیے VS Code Live Server ایکسٹینشن استعمال کریں
324- مستقل فارمیٹنگ کے لیے ESLint اور Prettier ایکسٹینشن انسٹال کریں
325- JavaScript کی ڈیبگنگ کے لیے براؤزر DevTools استعمال کریں
326- Vue پروجیکٹس کے لیے Vue DevTools براؤزر ایکسٹینشن انسٹال کریں
327 
328### کارکردگی کے پہلو
329 
330- بڑی تعداد میں ترجمہ شدہ فائلیں (50+ زبانیں) مکمل کلون کو بڑا بناتی ہیں
331- صرف مواد پر کام کے لیے shallow clone استعمال کریں: `git clone --depth 1`
332- انگریزی مواد پر کام کرتے وقت سرچ سے تراجم کو خارج کریں
333- بلڈ عمل پہلے رن پر سست ہو سکتا ہے (npm install, Vite build)
334 
335## سیکیورٹی کے پہلو
336 
337### ماحول کے متغیرات
338 
339- API کیز کو ذخیرہ میں کبھی جمع نہ کریں
340- `.env` فائلز استعمال کریں (جو پہلے سے `.gitignore` میں ہیں)
341- درکار ماحول کے متغیرات کو پروجیکٹ کی README میں دستاویز کریں
342 
343### Python پروجیکٹس
344 
345- ورچوئل ماحول استعمال کریں: `python -m venv venv`
346- dependencies کو اپ ٹو ڈیٹ رکھیں
347- GitHub ٹوکنز کو کم سے کم درکار اجازتوں کے ساتھ رکھیں
348 
349### GitHub Models کی رسائی
350 
351- GitHub Models کے لیے ذاتی رسائی کے ٹوکن (PAT) ضروری ہیں
352- ٹوکنز کو ماحول کے متغیرات کے طور پر محفوظ کریں
353- ٹوکنز یا اسناد کو کبھی جمع نہ کریں
354 
355## اضافی نوٹ
356 
357### ہدف سامعین
358 
359- ویب ڈیولپمنٹ کے مکمل مبتدی
360- طلباء اور خود آموز
361- اساتذہ جو کلاس رومز میں نصاب استعمال کرتے ہیں
362- مواد کو رسائی اور تدریجی مہارت سازی کے لیے ڈیزائن کیا گیا ہے
363 
364### تعلیمی فلسفہ
365 
366- پروجیکٹ پر مبنی تعلیمی طریقہ
367- بار بار علمی جانچ (کوئزز)
368- عملی کوڈنگ مشقیں
369- حقیقی دنیا کی ایپلیکیشن کی مثالیں
370- فریم ورکس سے پہلے بنیادی اصولوں پر توجہ
371 
372### ذخیرہ کا انتظام
373 
374- سیکھنے والوں اور تعاون کرنے والوں کی فعال کمیونٹی
375- dependencies اور مواد کی باقاعدہ اپ ڈیٹس
376- دیکھ بھال کرنے والوں کی جانب سے مسائل اور مباحثے کی نگرانی
377- GitHub Actions کے ذریعے ترجمہ کی خودکار اپ ڈیٹس
378 
379### متعلقہ وسائل
380 
381- [Microsoft Learn ماڈیولز](https://docs.microsoft.com/learn/)
382- [Student Hub کے وسائل](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) سیکھنے والوں کے لیے تجویز کردہ
384- اضافی کورسز: جنریٹو AI، ڈیٹا سائنس، ML، IoT نصاب دستیاب
385 
386### مخصوص پروجیکٹس کے ساتھ کام کرنا
387 
388انفرادی پروجیکٹس کی تفصیلی ہدایات کے لیے درج ذیل README فائلز دیکھیں:
389- `quiz-app/README.md` - Vue 3 کوئز ایپلیکیشن
390- `7-bank-project/README.md` - بینکنگ ایپلیکیشن کے ساتھ توثیق
391- `5-browser-extension/README.md` - براؤزر ایکسٹینشن ڈیولپمنٹ
392- `6-space-game/README.md` - کینوس پر مبنی گیم کی تیاری
393- `9-chat-project/README.md` - AI چیٹ اسسٹنٹ پروجیکٹ
394 
395### منوریپو ساخت
396 
397اگرچہ یہ روایتی monorepo نہیں ہے، مگر اس ذخیرے میں متعدد آزاد پروجیکٹس شامل ہیں:
398- ہر سبق خود سے مکمل ہے
399- پروجیکٹس ایک دوسرے کی dependencies شیئر نہیں کرتے
400- ایک ساتھ دوسرے پروجیکٹس کو متاثر کیے بغیر الگ الگ کام کریں
401- پورے نصاب کے تجربے کے لیے مکمل ذخیرہ کلون کریں
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**دھرنا**:  
407یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ اگرچه ہم درستگی کے لیے کوشاں ہیں، براہ کرم نوٹ کریں کہ خودکار ترجموں میں غلطیاں یا عدم درستگیاں ہو سکتی ہیں۔ اصل دستاویز اپنی مادری زبان میں ہی مستند ماخذ سمجھی جانی چاہیے۔ اہم معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم پر نہیں ہوگی۔
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->