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

AGENTS.md

परियोजना का अवलोकन

यह शुरुआती लोगों को वेब विकास की मूलभूत बातें सिखाने के लिए एक शैक्षिक पाठ्यक्रम रिपॉजिटरी है। पाठ्यक्रम माइक्रोसॉफ्ट क्लाउड एडवोकेट्स द्वारा विकसित 12-सप्ताह का व्यापक कोर्स है, जिसमें जावास्क्रिप्ट, CSS और HTML को कवर करने वाले 24 प्रैक्टिकल पाठ शामिल हैं।

मुख्य घटक

• शैक्षिक सामग्री: परियोजना-आधारित मॉड्यूल में व्यवस्थित 24 संरचित पाठ
• प्रैक्टिकल प्रोजेक्ट्स: टेरारियम, टाइपिंग गेम, ब्राउज़र एक्सटेंशन, स्पेस गेम, बैंकिंग ऐप, कोड एडिटर, और AI चैट असिस्टेंट
• इंटरएक्टिव क्विज़: 48 क्विज़, प्रत्येक में 3 प्रश्न (पाठ से पहले/बाद के आकलन)
• बहुभाषा समर्थन: GitHub Actions के माध्यम से 50+ भाषाओं में स्वचालित अनुवाद
• तकनीकें: HTML, CSS, जावास्क्रिप्ट, 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        # 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. योगदान दिशानिर्देशों का पालन करते हुए पुल अनुरोध सबमिट करें

शिक्षार्थियों के लिए

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       # 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 है
• सुनिश्चित करें कि मार्कडाउन लिंक मान्य हैं
• ब्राउज़र या Node.js में कोड उदाहरणों का परीक्षण करें
• सुनिश्चित करें कि अनुवाद उचित संरचना बनाए रखें

कोड शैली दिशानिर्देश

जावास्क्रिप्ट

• आधुनिक ES6+ सिंटैक्स का उपयोग करें
• प्रोजेक्ट्स में प्रदान किए गए मानक ESLint कॉन्फ़िगरेशन का पालन करें
• शैक्षिक स्पष्टता के लिए सार्थक वेरिएबल और फ़ंक्शन नामों का उपयोग करें
• शिक्षार्थियों के लिए अवधारणाओं को समझाने वाले टिप्पणियाँ जोड़ें
• जहां कॉन्फ़िगर किया गया हो, Prettier का उपयोग करके स्वरूपित करें

HTML/CSS

• सेमांटिक HTML5 तत्व
• उत्तरदायी डिज़ाइन सिद्धांत
• स्पष्ट क्लास नामकरण सम्मेलन
• शिक्षार्थियों के लिए CSS तकनीकों को समझाने वाले टिप्पणियाँ

Python

• 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      # 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 उत्पादन बंडल बनाता है
• स्थिर प्रोजेक्ट्स: कोई निर्माण चरण नहीं, फ़ाइलों को सीधे परोसें

पुल अनुरोध दिशानिर्देश

शीर्षक प्रारूप

परिवर्तन के क्षेत्र को इंगित करने वाले स्पष्ट, वर्णनात्मक शीर्षक का उपयोग करें:

• [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 चलाएं
   • सभी लिंटिंग त्रुटियों और चेतावनियों को ठीक करें

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+ भाषाएँ) का मतलब है कि पूर्ण क्लोन बड़े हैं
• केवल सामग्री पर काम करने के लिए शैलो क्लोन का उपयोग करें: git clone --depth 1
• अंग्रेजी सामग्री पर काम करते समय अनुवादों को खोजों से बाहर रखें
• पहली बार चलने पर निर्माण प्रक्रियाएँ धीमी हो सकती हैं (npm install, Vite build)

सुरक्षा विचार

पर्यावरण चर

• API कुंजियाँ कभी भी रिपॉजिटरी में कमिट नहीं की जानी चाहिए
• .env फ़ाइलों का उपयोग करें (पहले से .gitignore में)
• परियोजना READMEs में आवश्यक पर्यावरण चर दस्तावेज़ करें

Python प्रोजेक्ट्स

• वर्चुअल पर्यावरण का उपयोग करें: python -m venv venv
• डिपेंडेंसी को अपडेट रखें
• GitHub टोकन में न्यूनतम आवश्यक अनुमतियाँ होनी चाहिए

GitHub Models एक्सेस

• GitHub Models के लिए व्यक्तिगत एक्सेस टोकन (PAT) आवश्यक हैं
• टोकन को पर्यावरण चर के रूप में संग्रहीत किया जाना चाहिए
• टोकन या क्रेडेंशियल्स को कभी भी कमिट न करें

अतिरिक्त नोट्स

लक्षित दर्शक

• वेब विकास के लिए पूर्ण शुरुआती
• छात्र और स्वयं-शिक्षार्थी
• कक्षाओं में पाठ्यक्रम का उपयोग करने वाले शिक्षक
• सामग्री पहुंच और कौशल निर्माण के लिए डिज़ाइन की गई है

शैक्षिक दर्शन

• परियोजना-आधारित शिक्षण दृष्टिकोण
• बार-बार ज्ञान जांच (क्विज़)
• हाथों-हाथ कोडिंग अभ्यास
• वास्तविक दुनिया के अनुप्रयोग उदाहरण
• फ्रेमवर्क से पहले मूलभूत बातों पर ध्यान केंद्रित

रिपॉजिटरी रखरखाव

• शिक्षार्थियों और योगदानकर्ताओं का सक्रिय समुदाय
• डिपेंडेंसी और सामग्री के नियमित अपडेट
• मुद्दों और चर्चाओं की मेंटेनर्स द्वारा निगरानी
• GitHub Actions के माध्यम से अनुवाद अपडेट स्वचालित

संबंधित संसाधन

• Microsoft Learn मॉड्यूल
• स्टूडेंट हब संसाधन
• 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 का उपयोग करके अनुवादित किया गया है। जबकि हम सटीकता सुनिश्चित करने का प्रयास करते हैं, कृपया ध्यान दें कि स्वचालित अनुवाद में त्रुटियां या अशुद्धियां हो सकती हैं। मूल भाषा में उपलब्ध मूल दस्तावेज़ को प्रामाणिक स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए, पेशेवर मानव अनुवाद की सिफारिश की जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम उत्तरदायी नहीं हैं।