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

AGENTS.md

Muhtasari wa Mradi

Huu ni hifadhidata ya mtaala wa kielimu kwa kufundisha misingi ya maendeleo ya wavuti kwa wanaoanza. Mtaala ni kozi kamili ya wiki 12 iliyotengenezwa na Microsoft Cloud Advocates, inayojumuisha masomo 24 ya vitendo yanayochukua JavaScript, CSS, na HTML.

Vipengele Muhimu

• Maudhui ya Kielimu: Masomo 24 yaliyoandaliwa kwa mfululizo katika moduli za miradi
• Miradi ya Vitendo: Terrarium, Mchezo wa Kuandika, Kiongezeo cha Kivinjari, Mchezo wa Anga, Programu ya Benki, Mhariri wa Msimbo, na Msaidizi wa AI wa Mazungumzo
• Mtihani wa Kuelewa: Mitihani 48 yenye maswali 3 kila moja (kipimo kabla/baada ya somo)
• Msaada wa Lugha Nyingi: Tafsiri za kiotomatiki kwa lugha zaidi ya 50 kupitia GitHub Actions
• Teknolojia: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (kwa miradi ya AI)

Mifumo ya Ujenzi

• Hifadhidata ya kielimu yenye muundo wa masomo
• Kila saraka ya somo ina README, mifano ya msimbo, na suluhisho
• Miradi huru katika saraka tofauti (quiz-app, miradi mbalimbali ya somo)
• Mfumo wa tafsiri unaotumia GitHub Actions (co-op-translator)
• Nyaraka zinatolewa kwa kupitia Docsify na zinapatikana kama PDF

Amri za Kuanzisha

Hifadhidata hii ni kwa matumizi hasa ya maudhui ya kielimu. Kwa kufanya kazi na miradi maalum:

Usanidi wa Hifadhidata Kuu

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

Usanidi wa Quiz App (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Anza seva ya maendeleo
npm run build      # Jenga kwa ajili ya uzalishaji
npm run lint       # Endesha ESLint

API ya Mradi wa Benki (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Anzisha seva ya API
npm run lint       # Endesha ESLint
npm run format     # Fomati kwa Prettier

Miradi ya Kiongezeo cha Kivinjari

cd 5-browser-extension/solution
npm install
# Fuata maelekezo maalum ya pili ya upakiaji ya kivinjari

Miradi ya Mchezo wa Anga

cd 6-space-game/solution
npm install
# Fungua index.html kwenye kivinjari au tumia Live Server

Mradi wa Mazungumzo (Python Backend)

cd 9-chat-project/solution/backend/python
pip install openai
# Weka mabadiliko ya mazingira ya GITHUB_TOKEN
python api.py

Mchakato wa Maendeleo

Kwa Watoa Maudhui

1. Fungua hifadhidata kwa akaunti yako ya GitHub
2. Dondoa nakala ya hifadhidata mahali pako pa kazi
3. Tengeneza tawi jipya kwa mabadiliko yako
4. Fanya mabadiliko kwenye maudhui ya somo au mifano ya msimbo
5. Jaribu mabadiliko ya msimbo katika saraka za miradi husika
6. Wasilisha maombi ya Pull Requests kufuatilia miongozo ya michango

Kwa Wanafunzi

1. Fanya fork au clone hifadhidata
2. Tembelea saraka za masomo mfululizo
3. Soma mafaili ya README kwa kila somo
4. Kamilisha mtihani wa kuelewa kabla ya somo kwenye https://ff-quizzes.netlify.app/web/
5. Fanya kazi kupitia mifano ya msimbo katika saraka za somo
6. Kamilisha mazoezi na changamoto
7. Chukua mitihani ya kuelewa baada ya somo

Maendeleo Moja kwa Moja

• Nyaraka: Endesha docsify serve kwenye mzizi (bandari 3000)
• Quiz App: Endesha npm run dev katika saraka ya quiz-app
• Miradi: Tumia kiendelezi cha VS Code Live Server kwa miradi ya HTML
• Miradi ya API: Endesha npm start katika saraka husika za API

Maelekezo ya Kupima

Kupima Quiz App

cd quiz-app
npm run lint       # Angalia kwa masuala ya mtindo wa msimbo
npm run build      # Thibitisha ujenzi unafanikiwa

Kupima API ya Benki

cd 7-bank-project/api
npm run lint       # Kagua kwa matatizo ya mtindo wa msimbo
node server.js     # Hakikisha seva inaanza bila makosa

Mbinu za Kupima kwa Jumla

• Hii ni hifadhidata ya kielimu bila vipimo vya kiotomatiki kamilifu
• Kupima kwa mkono kunazingatia:
  • Mifano ya msimbo inafanya kazi bila makosa
  • Viungo katika nyaraka vinatumika kikamilifu
  • Ujenzi wa miradi unakamilika kwa mafanikio
  • Mifano inafuata mbinu bora

Ukaguzi Kabla ya Kuwasilisha

• Endesha npm run lint katika saraka zenye package.json
• Hakiki viungo vya markdown kama vinavyofaa
• Jaribu mifano ya msimbo katika kivinjari au Node.js
• Hakikisha tafsiri zinaifuata muundo mzuri

Miongozo ya Mtindo wa Msimbo

JavaScript

• Tumia sarufi za kisasa za ES6+
• Fuata usanidi wa ESLint uliotolewa katika miradi
• Tumia majina ya maana kwa mabadiliko na kazi kwa ufafanuzi wa kielimu
• Ongeza maelezo kuelezea dhana kwa wanafunzi
• Panga kwa kutumia Prettier pale panapowezekana

HTML/CSS

• Vipengele vya maana vya HTML5
• Kanuni za muundo unaobadilika katika skrini tofauti
• Mipangilio wazi ya majina ya madarasa
• Maelezo kuelezea mbinu za CSS kwa wanafunzi

Python

• Miongozo ya mtindo wa PEP 8
• Mifano ya msimbo iliyo wazi na ya kielimu
• Dalili za aina inapofaa kwa ajili ya kujifunza

Nyaraka za Markdown

• Hieraki wazi ya vichwa
• Vizuizi vya msimbo vyenye lugha ya kuainisha
• Viungo vya rasilimali za ziada
• Picha na picha ndogo katika saraka za images/
• Maandishi ya alt kwa picha kwa ajili ya ufikiaji rahisi

Usanidi wa Faili

• Masomo nambari mfululizo (1-getting-started-lessons, 2-js-basics, nk.)
• Kila mradi una saraka za solution/ na mara nyingi start/ au your-work/
• Picha huhifadhiwa katika saraka za images/ za masomo binafsi
• Tafsiri zinaweza kupatikana katika muundo wa translations/{language-code}/

Ujenzi na Uenezaji

Uenezaji wa Quiz App (Azure Static Web Apps)

quiz-app imewekwa kwa ajili ya uenezaji wa Azure Static Web Apps:

cd quiz-app
npm run build      # Inaunda folda ya dist/
# Inaweka kupitia workflow ya GitHub Actions wakati wa kushinikiza kwenye main

Usanidi wa Azure Static Web Apps:

• Mahali pa App: /quiz-app
• Mahali pa matokeo: dist
• Mchakato: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Uundaji wa PDF wa Nyaraka

npm install                    # Sakinisha docsify-to-pdf
npm run convert               # Tengeneza PDF kutoka kwa docs

Nyaraka za Docsify

npm install -g docsify-cli    # Sakinisha Docsify kimataifa
docsify serve                 # Tumikia kwenye localhost:3000

Ujenzi wa Miradi Maalum

Kila saraka ya mradi inaweza kuwa na mchakato wake wa ujenzi:

• Miradi ya Vue: npm run build hutengeneza vifurushi vya uzalishaji
• Miradi ya Static: Hakuna hatua ya ujenzi, hudumu faili moja kwa moja

Miongozo ya Maombi ya Pull

Muundo wa Kichwa

Tumia vichwa wazi, vinavyoelezea eneo la mabadiliko:

• [Quiz-app]ongeza mtihani mpya wa somo X
• [Lesson-3]rekebisha makosa ya herufi katika mradi wa terrarium
• [Translation]ongeza tafsiri ya Kihispania kwa somo 5
• [Docs]sasisha maelekezo ya usanidi

Ukaguzi Unaohitajika

Kabla ya kuwasilisha PR:

1. Ubora wa Msimbo:

   • Endesha npm run lint katika saraka za miradi zilizoathirika
   • Rekebisha makosa na onyo zote za lint

2. Uhakiki wa Ujenzi:

   • Endesha npm run build ikiwa inafaa
   • Hakikisha hakuna makosa ya ujenzi

3. Uhakiki wa Viungo:

   • Jaribu viungo vyote vya markdown
   • Hakiki marejeleo ya picha yanafanya kazi

4. Ukaguzi wa Maudhui:

   • Soma kwa makini kwa makosa ya sarufi na tahajia
   • Hakikisha mifano ya msimbo ni sahihi na ya kielimu
   • Hakiki tafsiri zinahifadhi maana asilia

Mahitaji ya Michango

• Kubali CLA ya Microsoft (ukaguzi wa moja kwa moja kwenye PR ya kwanza)
• Fuata Kanuni ya Maadili ya Chanzo Huria ya Microsoft Microsoft Open Source Code of Conduct
• Tazama CONTRIBUTING.md kwa miongozo ya kina
• Taja nambari za masuala katika maelezo ya PR ikiwa inahitajika

Mchakato wa Ukaguzi

• PR hupitiwa na watunza na jamii
• Ufafanuzi wa kielimu unazingatiwa kipaumbele
• Mifano ya msimbo inapaswa kufuata mbinu bora za sasa
• Tafsiri hupitiwa kwa usahihi na uangalifu wa kitamaduni

Mfumo wa Tafsiri

Tafsiri za Kiotomatiki

• Inatumia GitHub Actions na mchakato wa co-op-translator
• Hutatfsiri kwa lugha zaidi ya 50 kiotomatiki
• Faili za chanzo ziko katika saraka kuu
• Faili za tafsiri ziko katika saraka za translations/{language-code}/

Kuongeza Maboresho ya Tafsiri za Mkono

1. Tafuta faili katika translations/{language-code}/
2. Fanya maboresho huku ukihifadhi muundo
3. Hakikisha mifano ya msimbo bado inafanya kazi
4. Jaribu maudhui ya mtihani yaliyotafsiriwa

Metadata ya Tafsiri

Faili za tafsiri zina kichwa cha metadata:

<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->

Ugunduzi na Utatuzi wa Matatizo

Masuala ya Kawaida

Programu ya Quiz haianzi:

• Angalia toleo la Node.js (inapendekezwa v14+)
• Futa node_modules na package-lock.json, endesha tena npm install
• Angalia mkatano wa bandari (chaguo-msingi: Vite hutumia bandari 5173)

Server ya API haianzi:

• Hakiki toleo la Node.js linatosha (node >=10)
• Hakiki kama bandari tayari imetumika
• Hakikisha utegemezi wote umewekwa kwa npm install

Kiongezeo cha kivinjari hakianzi:

• Hakiki json ya manifest ni sahihi
• Angalia makosa kwenye console ya kivinjari
• Fuata maelekezo ya usakinishaji ya kiongezeo cha kivinjari

Masuala ya mradi wa mazungumzo ya Python:

• Hakikisha kifurushi cha OpenAI kimewekwa: pip install openai
• Hakiki maadili ya mazingira ya GITHUB_TOKEN yamewekwa
• Angalia ruhusa za kufikia GitHub Models

Docsify hautumikii nyaraka:

• Sakinisha docsify-cli kimataifa: npm install -g docsify-cli
• Endesha kutoka saraka kuu ya hifadhidata
• Hakiki kama docs/_sidebar.md ipo

Vidokezo vya Mazingira ya Maendeleo

• Tumia VS Code na kiendelezi cha Live Server kwa miradi ya HTML
• Sakinisha kiendelezi cha ESLint na Prettier kwa mtindo thabiti
• Tumia DevTools za kivinjari kwa ugunduzi wa makosa ya JavaScript
• Kwa miradi ya Vue, sakinisha kiendelezi cha Vue DevTools kwa kivinjari

Mambo ya Utendaji

• Idadi kubwa ya faili zilizotafsiriwa (lugha 50+) hufanya nakala kamili kuwa kubwa
• Tumia nakala ya kina kidogo ikiwa unafanya kazi pekee na maudhui: git clone --depth 1
• Epuka tafutaji za tafsiri unaporatibu kazi kwa maudhui ya Kiingereza
• Mchakato wa ujenzi unaweza kuwa polepole mara ya kwanza (npm install, Vite build)

Mambo ya Usalama

Vigezo vya Mazingira

• Mofadhi za API hazipaswi kuwekwa hifadhidanini
• Tumia faili za .env (ziko katika .gitignore)
• Andika vigezo vya mazingira vinavyohitajika katika README za miradi

Miradi ya Python

• Tumia mazingira ya kipengele: python -m venv venv
• Endelea kusasisha utegemezi
• Vidhibiti vya GitHub vinapaswa kuwa na ruhusa ndogo zinazohitajika

Ufikiaji wa GitHub Models

• Vidhibiti vya Ufikiaji wa Binafsi (PAT) vinahitajika kwa GitHub Models
• Vidhibiti vinapaswa kuhifadhiwa kama vigezo vya mazingira
• Kamwe usiweka vidhibiti au nyaraka za siri kwenye hifadhidata

Vidokezo Ziada

Watu Wanaolengwa

• Wanaoanza kabisa katika maendeleo ya wavuti
• Wanafunzi na wanaojifunza pekee
• Walimu wanaotumia mtaala huyu kwenye madarasa
• Maudhui yameundwa kwa ufikiaji rahisi na kujenga ujuzi kwa hatua

Falsafa ya Elimu

• Mbinu za kujifunza kupitia mradi
• Ukaguzi wa mara kwa mara wa maarifa (mitihani)
• Mazoezi ya coding ya vitendo
• Mifano ya matumizi halisi duniani
• Kipaumbele katika misingi kabla ya mifumo ya kielekezi

Matengenezo ya Hifadhidata

• Jamii hai ya wanafunzi na wachangiaji
• Sasisho za mara kwa mara kwa utegemezi na maudhui
• Masuala na majadiliano huangaliwa na watunza
• Sasisho za tafsiri kiotomatiki kupitia GitHub Actions

Rasilimali Zinazohusiana

• Moduli za Microsoft Learn
• Rasilimali za Student Hub
• GitHub Copilot inashauriwa kwa wanafunzi
• Kozi za ziada: AI ya kuzalisha, Sayansi ya Data, ML, IoT zinazopatikana

Kufanya Kazi na Miradi Maalum

Kwa maagizo ya kina juu ya miradi binafsi, rejelea mafaili ya README katika:

• quiz-app/README.md - Programu ya quiz ya Vue 3
• 7-bank-project/README.md - Programu ya benki yenye uthibitishaji
• 5-browser-extension/README.md - Maendeleo ya kiongezeo cha kivinjari
• 6-space-game/README.md - Maendeleo ya mchezo wa canvas
• 9-chat-project/README.md - Mradi wa msaidizi wa mazungumzo wa AI

Muundo wa Monorepo

Ingawa si monorepo ya kawaida, hifadhidata hii ina miradi huru mingi:

• Kila somo lina utaratibu wake binafsi
• Miradi haigawani utegemezi
• Fanya kazi kwenye miradi binafsi bila kuathiri mingine
• Dondoa hifadhidata yote kwa uzoefu kamili wa mtaala

---

Kumbusho:
Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI Co-op Translator. Wakati tunajitahidi kwa usahihi, tafadhali fahamu kwamba tafsiri za kiotomatiki zinaweza kuwa na makosa au kasoro. Hati ya asili katika lugha yake ya asili inapaswa kuchukuliwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya kitaalamu ya binadamu inapendekezwa. Hatubebei dhamana kwa kutokuelewana au tafsiri potofu zinazotokana na matumizi ya tafsiri hii.