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

AGENTS.md

סקירת הפרויקט

זהו מאגר תוכן חינוכי ללימוד יסודות פיתוח ווב למתחילים. תוכנית הלימודים היא קורס מקיף בן 12 שבועות שפותח על ידי Microsoft Cloud Advocates, הכולל 24 שיעורים מעשיים העוסקים ב-JavaScript, CSS ו-HTML.

רכיבים מרכזיים

• תוכן חינוכי: 24 שיעורים מאורגנים במודולים מבוססי פרויקטים
• פרויקטים מעשיים: טראריום, משחק הקלדה, תוסף דפדפן, משחק חלל, אפליקציית בנקאות, עורך קוד ועוזר צ׳אט מבוסס AI
• חידונים אינטראקטיביים: 48 חידונים עם 3 שאלות כל אחד (הערכות לפני/אחרי השיעור)
• תמיכה רב-שפתית: תרגומים אוטומטיים ל-50+ שפות דרך GitHub Actions
• טכנולוגיות: 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

פרויקט צ׳אט (Backend בפייתון)

cd 9-chat-project/solution/backend/python
pip install openai
# הגדר את משתנה הסביבה GITHUB_TOKEN
python api.py

זרימת עבודה בפיתוח

עבור תורמים לתוכן

1. צור Fork למאגר לחשבון ה-GitHub שלך
2. שכפל את ה-Fork במחשב המקומי שלך
3. צור סניף חדש לשינויים שלך
4. בצע שינויים בתוכן השיעורים או בדוגמאות הקוד
5. בדוק כל שינויי קוד בתיקיות הפרויקט הרלוונטיות
6. הגש בקשות משיכה בהתאם להנחיות התרומה

עבור הלומדים

1. צור Fork או שכפל את המאגר
2. עבור רצוף בין תיקיות השיעורים
3. קרא את קבצי README עבור כל שיעור
4. השלם חידוני לפני שיעור בכתובת https://ff-quizzes.netlify.app/web/
5. עבד על דוגמאות הקוד בתיקיות השיעורים
6. השלם משימות ואתגרים
7. בצע חידוני לאחר השיעור

פיתוח חי

• תיעוד: הפעל docsify serve בתיקיית השורש (פורט 3000)
• אפליקציית חידונים: הפעל npm run dev בתיקיית quiz-app
• פרויקטים: השתמש ב-VS Code Live Server להפעלת פרויקטים HTML
• פרויקטי API: הפעל npm start בתיקיות ה-API המתאימות

הוראות בדיקה

בדיקת אפליקציית חידונים

cd quiz-app
npm run lint       # בדוק שגיאות בסגנון הקוד
npm run build      # אמת שהבניין מצליח

בדיקת API של הבנק

cd 7-bank-project/api
npm run lint       # לבדוק בעיות בסגנון הקוד
node server.js     # לאמת שהשרת מתחיל ללא שגיאות

גישת בדיקה כללית

• זהו מאגר חינוכי ללא בדיקות אוטומטיות מקיפות
• בדיקות ידניות מתמקדות ב:
  • הפעלת דוגמאות הקוד ללא שגיאות
  • קישורים בתיעוד עובדים כשורה
  • פרויקטים נבנים בהצלחה
  • דוגמאות עוקבות אחר נהלי עבודה מומלצים

בדיקות לפני הגשה

• הפעל npm run lint בתיקיות המכילות package.json
• ודא כי קישורי markdown תקינים
• בדוק דוגמאות קוד בדפדפן או ב-Node.js
• וודא שהתרגומים שומרים על המבנה הנכון

קווי הנחיה לסגנון קוד

JavaScript

• השתמש בתחביר מודרני ES6+
• עקוב אחר הגדרות ESLint סטנדרטיות בפרויקטים
• השתמש בשמות משתנים ופונקציות משמעותיים לצורך הבהרה חינוכית
• הוסף הערות המסבירות מושגים ללומדים
• עיצוב באמצעות Prettier כשמוגדר

HTML/CSS

• אלמנטים סמליים ב-HTML5
• עקרונות עיצוב רספונסיבי
• קונבנציות ברורות לשמות מחלקות
• הערות המסבירות טכניקות CSS ללומדים

Python

• קווי הנחיה בסגנון PEP 8
• דוגמאות קוד ברורות וחינוכיות
• רמזי טיפוס כאשר זה מועיל ללמידה

תיעוד ב-Markdown

• היררכיית כותרות ברורה
• בלוקי קוד עם הגדרת שפה
• קישורים למשאבים נוספים
• צילומי מסך ותמונות בתיקיות images/
• טקסט חלופי לתמונות לנגישות

ארגון קבצים

• שיעורים ממוספרים בסדר (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 בעת דחיפה לענף main

הגדרות 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               # יצירת PDF מ-docs

תיעוד Docsify

npm install -g docsify-cli    # התקן את Docsify באופן גלובלי
docsify serve                 # שרת על localhost:3000

בניות ייחודיות לפרויקט

לכל תיקיית פרויקט יכול להיות תהליך בנייה משלה:

• פרויקטים ב-Vue: הפעל npm run build ליצירת חבילות ייצור
• פרויקטים סטטיים: אין שלב בנייה, מגישים את הקבצים ישירות

קווי הנחיה לבקשות משיכה

פורמט הכותרת

השתמש בכותרות ברורות ומתארות עם אזור השינוי:

• [Quiz-app] הוסף חידון חדש לשיעור X
• [Lesson-3] תיקון שגיאת הקלדה בפרויקט טראריום
• [Translation] הוסף תרגום ספרדי לשיעור 5
• [Docs] עדכן הוראות התקנה

בדיקות נדרשות

לפני הגשת PR:

1. איכות קוד:

   • הפעל npm run lint בתיקיות הפרויקט הרלוונטיות
   • תקן כל שגיאה או אזהרה

2. אימות בנייה:

   • הפעל npm run build אם נדרש
   • וודא שאין שגיאות בנייה

3. אימות קישורים:

   • בדוק את כל קישורי ה-markdown
   • ודא שהקישורים לתמונות תקינים

4. סקירת תוכן:

   • ערוך הגהה לאיות ותחביר
   • ודא שהדוגמאות נכונות וחינוכיות
   • וודא שהתרגומים שומרים על המשמעות המקורית

דרישות לתרומה

• אישור CLA של מיקרוסופט (בדיקה אוטומטית בעת PR ראשון)
• עקוב אחר קוד ההתנהגות של Microsoft Open Source
• עיין בקובץ CONTRIBUTING.md להנחיות מפורטות
• התייחס למספרי נושאים בתיאור ה-PR אם רלוונטי

תהליך סקירה

• בקשות משיכה נסקרות על ידי מנהלים והקהילה
• דגש על בהירות חינוכית
• דוגמאות קוד צריכות לעקוב אחר נהלי עבודה מומלצים
• תרגומים נבדקים לדיוק והתאמה תרבותית

מערכת תרגום

תרגום אוטומטי

• משתמש ב-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 מעוצב כראוי
• בדוק בלוג הדפדפן לשגיאות
• עקוב אחר הוראות ההתקנה הספציפיות לדפדפן

בעיות בפרויקט צ׳אט בפייתון:

• ודא שהחבילה OpenAI מותקנת: pip install openai
• בדוק שהמשתנה הסביבתי GITHUB_TOKEN מוגדר
• בדוק הרשאות גישה למודלים דרך GitHub

Docsify לא מגישה תיעוד:

• התקן docsify-cli גלובלית: npm install -g docsify-cli
• הפעל מהתיקייה השורשית של המאגר
• ודא שקיים הקובץ docs/_sidebar.md

טיפים לסביבת פיתוח

• השתמש ב-VS Code עם הרחבת Live Server לפרויקטים ב-HTML
• התקן את ההרחבות ESLint ו-Prettier לעיצוב עקבי
• השתמש בכלי הפיתוח של הדפדפן לניפוי שגיאות ב-JavaScript
• לפרויקטים ב-Vue התקן Vue DevTools בדפדפן

שיקולי ביצועים

• מספר גדול של קבצי תרגום (50+ שפות) גורם לשכפולים מלאים להיות כבדים
• השתמש בשכפול רדוד אם עובד רק על תוכן: git clone --depth 1
• וחרג תוצאות חיפוש מתרגומים בעת עבודה על תוכן באנגלית
• תהליכי בנייה עלולים להיות איטיים בהרצה הראשונה (npm install, בניית Vite)

שיקולי אבטחה

משתני סביבה

• אסור לשמור מפתחות API במאגר
• השתמש בקבצי .env (כבר ב-.gitignore)
• תעד משתני סביבה נדרשים בקבצי README של הפרויקטים

פרויקטים בפייתון

• השתמש בסביבות וירטואליות: python -m venv venv
• שמור על עדכון התלויות
• אסימונים של GitHub צריכים להיות עם הרשאות מינימליות

גישה למודלים של GitHub

• דרושים Personal Access Tokens (PAT) לגישה למודלים
• יש לאחסן אסימונים במשתני סביבה
• לעולם לא לשמור אסימונים או אישורים בקוד

הערות נוספות

קהל יעד

• מתחילים מלאים בפיתוח ווב
• סטודנטים ולומדים עצמאיים
• מורים המשתמשים בתוכנית בכיתות לימוד
• התוכן מיועד לנגישות ובניית מיומנויות בהדרגה

הפילוסופיה החינוכית

• גישה מבוססת פרויקטים ללמידה
• בדיקות ידע תכופות (חידונים)
• תרגילי קידוד מעשיים
• דוגמאות לשימוש בעולם האמיתי
• דגש על יסודות לפני מבני עבודה

תחזוקת המאגר

• קהילה פעילה של לומדים ותורמים
• עדכונים שוטפים לתלויות ולתוכן
• מעקב אחר נושאים ודיונים על ידי מנהלים
• עדכוני תרגום אוטומטיים באמצעות GitHub Actions

משאבים נלווים

• מודולי Microsoft Learn
• משאבי Student Hub
• GitHub Copilot מומלץ ללומדים
• קורסים נוספים: AI גנרטיבי, מדעי נתונים, למידת מכונה, 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

מבנה מונורפו

למרות שאינו מונורפו מסורתי, מאגר זה מכיל מספר פרויקטים עצמאיים:

• כל שיעור עצמאי
• הפרויקטים אינם חולקים תלותיות
• עבוד על פרויקטים נפרדים ללא השפעה על אחרים
• שכפל את כל המאגר לחוויית תוכנית לימודים מלאה

---

כתב ויתור:
מסמך זה תורגם באמצעות שירות תרגום מבוסס בינה מלאכותית Co-op Translator. למרות שאנו שואפים לדיוק, יש להיות מודעים לכך שתירגומים אוטומטיים עלולים להכיל שגיאות או אי-דיוקים. המסמך המקורי בשפת המקור שלו הוא המקור הסמכותי. למידע קריטי מומלץ להשתמש בתרגום מקצועי של אדם. אנו לא אחראים לכל אי-הבנה או פרשנות שגויה הנובעת משימוש בתרגום זה.