diff --git a/translated_images/1.b6da8c1394b07491.he.png b/translated_images/1.b6da8c1394b07491.he.png
new file mode 100644
index 000000000..b7196681f
Binary files /dev/null and b/translated_images/1.b6da8c1394b07491.he.png differ
diff --git a/translated_images/1.b6da8c1394b07491.id.png b/translated_images/1.b6da8c1394b07491.id.png
new file mode 100644
index 000000000..fc1ecf31b
Binary files /dev/null and b/translated_images/1.b6da8c1394b07491.id.png differ
diff --git a/translated_images/1.b6da8c1394b07491.ms.png b/translated_images/1.b6da8c1394b07491.ms.png
new file mode 100644
index 000000000..4abfa7efe
Binary files /dev/null and b/translated_images/1.b6da8c1394b07491.ms.png differ
diff --git a/translated_images/1.b6da8c1394b07491.sw.png b/translated_images/1.b6da8c1394b07491.sw.png
new file mode 100644
index 000000000..5dcf910a1
Binary files /dev/null and b/translated_images/1.b6da8c1394b07491.sw.png differ
diff --git a/translated_images/1.b6da8c1394b07491.tl.png b/translated_images/1.b6da8c1394b07491.tl.png
new file mode 100644
index 000000000..60d13ff58
Binary files /dev/null and b/translated_images/1.b6da8c1394b07491.tl.png differ
diff --git a/translated_images/1.b6da8c1394b07491.vi.png b/translated_images/1.b6da8c1394b07491.vi.png
new file mode 100644
index 000000000..5dfb49b75
Binary files /dev/null and b/translated_images/1.b6da8c1394b07491.vi.png differ
diff --git a/translated_images/1.cc07a5cbe114ad1d.he.png b/translated_images/1.cc07a5cbe114ad1d.he.png
new file mode 100644
index 000000000..87c1ce9b5
Binary files /dev/null and b/translated_images/1.cc07a5cbe114ad1d.he.png differ
diff --git a/translated_images/1.cc07a5cbe114ad1d.id.png b/translated_images/1.cc07a5cbe114ad1d.id.png
new file mode 100644
index 000000000..49b82350a
Binary files /dev/null and b/translated_images/1.cc07a5cbe114ad1d.id.png differ
diff --git a/translated_images/1.cc07a5cbe114ad1d.ms.png b/translated_images/1.cc07a5cbe114ad1d.ms.png
new file mode 100644
index 000000000..d3e171873
Binary files /dev/null and b/translated_images/1.cc07a5cbe114ad1d.ms.png differ
diff --git a/translated_images/1.cc07a5cbe114ad1d.sw.png b/translated_images/1.cc07a5cbe114ad1d.sw.png
new file mode 100644
index 000000000..390a3902d
Binary files /dev/null and b/translated_images/1.cc07a5cbe114ad1d.sw.png differ
diff --git a/translated_images/1.cc07a5cbe114ad1d.tl.png b/translated_images/1.cc07a5cbe114ad1d.tl.png
new file mode 100644
index 000000000..fcb0eb03a
Binary files /dev/null and b/translated_images/1.cc07a5cbe114ad1d.tl.png differ
diff --git a/translated_images/1.cc07a5cbe114ad1d.vi.png b/translated_images/1.cc07a5cbe114ad1d.vi.png
new file mode 100644
index 000000000..21c8fde85
Binary files /dev/null and b/translated_images/1.cc07a5cbe114ad1d.vi.png differ
diff --git a/translated_images/2.1dae52ff08042246.he.png b/translated_images/2.1dae52ff08042246.he.png
new file mode 100644
index 000000000..72854bd8c
Binary files /dev/null and b/translated_images/2.1dae52ff08042246.he.png differ
diff --git a/translated_images/2.1dae52ff08042246.id.png b/translated_images/2.1dae52ff08042246.id.png
new file mode 100644
index 000000000..5159621cd
Binary files /dev/null and b/translated_images/2.1dae52ff08042246.id.png differ
diff --git a/translated_images/2.1dae52ff08042246.ms.png b/translated_images/2.1dae52ff08042246.ms.png
new file mode 100644
index 000000000..b249c5233
Binary files /dev/null and b/translated_images/2.1dae52ff08042246.ms.png differ
diff --git a/translated_images/2.1dae52ff08042246.sw.png b/translated_images/2.1dae52ff08042246.sw.png
new file mode 100644
index 000000000..98e2213c6
Binary files /dev/null and b/translated_images/2.1dae52ff08042246.sw.png differ
diff --git a/translated_images/2.1dae52ff08042246.tl.png b/translated_images/2.1dae52ff08042246.tl.png
new file mode 100644
index 000000000..d8e75f404
Binary files /dev/null and b/translated_images/2.1dae52ff08042246.tl.png differ
diff --git a/translated_images/2.1dae52ff08042246.vi.png b/translated_images/2.1dae52ff08042246.vi.png
new file mode 100644
index 000000000..cd808f078
Binary files /dev/null and b/translated_images/2.1dae52ff08042246.vi.png differ
diff --git a/translated_images/after-codeswing-extension-pb.0ebddddcf73b5509.he.png b/translated_images/after-codeswing-extension-pb.0ebddddcf73b5509.he.png
new file mode 100644
index 000000000..2c4181332
Binary files /dev/null and b/translated_images/after-codeswing-extension-pb.0ebddddcf73b5509.he.png differ
diff --git a/translated_images/after-codeswing-extension-pb.0ebddddcf73b5509.id.png b/translated_images/after-codeswing-extension-pb.0ebddddcf73b5509.id.png
new file mode 100644
index 000000000..703fed12b
Binary files /dev/null and b/translated_images/after-codeswing-extension-pb.0ebddddcf73b5509.id.png differ
diff --git a/translations/sw/7-bank-project/4-state-management/README.md b/translations/sw/7-bank-project/4-state-management/README.md
index 1e7c2a710..1984cc352 100644
--- a/translations/sw/7-bank-project/4-state-management/README.md
+++ b/translations/sw/7-bank-project/4-state-management/README.md
@@ -1,118 +1,242 @@
-# Jenga Programu ya Benki Sehemu ya 4: Dhana za Usimamizi wa Hali
+# Jenga App ya Benki Sehemu ya 4: Dhana za Usimamizi wa Hali
-## Maswali ya Awali ya Somo
+## ⚡ Unachoweza Kufanya Katika Dakika 5 Zijazo
-[Maswali ya awali ya somo](https://ff-quizzes.netlify.app/web/quiz/47)
+**Njia ya Mwanzo wa Haraka kwa Waendelezaji Wenye Muda Mfupi**
+
+```mermaid
+flowchart LR
+ A[⚡ Dakika 5] --> B[Chunguza matatizo ya hali]
+ B --> C[Tengeneza kitu cha hali ya kati]
+ C --> D[Ongeza kazi ya updateState]
+ D --> E[Tazama maboresho ya haraka]
+```
+- **Dakika 1**: Jaribu tatizo la hali ya sasa - ingia, tazama upya ukurasa, angalia kuondolewa kwa kiingilio
+- **Dakika 2**: Badilisha `let account = null` na `let state = { account: null }`
+- **Dakika 3**: Unda kazi rahisi ya `updateState()` kwa sasisho za kidhibitiwa
+- **Dakika 4**: Sasisha moja ya kazi ili kutumia muundo mpya
+- **Dakika 5**: Jaribu utabiri ulioboreshwa na uwezo wa kutatua matatizo
+
+**Jaribio la Haraka la Uchunguzi**:
+```javascript
+// Kabla: Hali iliyosambazwa
+let account = null; // Imepotea wakati wa kufungua upya!
+
+// Baada: Hali iliyojumuishwa
+let state = Object.freeze({ account: null }); // Imebadiliwa na inafuata!
+```
+
+**Kwa Nini Hii ni Muhimu**: Katika dakika 5, utashuhudia mabadiliko kutoka kwa usimamizi wa hali usiovurugika hadi mifumo inayoweza kutabirika na kutatuliwa kwa urahisi. Hii ni msingi unaofanya programu changamano kuwa rahisi kudumishwa.
+
+## 🗺️ Safari Yako ya Kujifunza Kupitia Utaalamu wa Usimamizi wa Hali
+
+```mermaid
+journey
+ title Kutoka Hali Zilizotawanyika hadi Usanifu wa Kitaalamu
+ section Kugundua Matatizo
+ Tambua matatizo ya upotevu wa hali: 3: You
+ Elewa masasisho yaliyotawanyika: 4: You
+ Tambua mahitaji ya usanifu: 6: You
+ section Kuweka Udhibiti Kando
+ Tengeneza kitu kimoja cha hali: 5: You
+ Tekeleza masasisho yanayodhibitiwa: 7: You
+ Ongeza mifumo isiyobadilika: 8: You
+ section Kuongeza Kudumu
+ Tekeleza localStorage: 6: You
+ Hudumia serialization: 7: You
+ Tengeneza kuendelea kwa kikao: 9: You
+ section Kuweka Mizani Kuwa Safi
+ Takasa uchakavu wa data: 5: You
+ Jenga mifumo ya kusasisha: 8: You
+ Fikia usawa bora: 9: You
+```
+**Mwenendo wa Safari Yako**: Mwisho wa somo hili, utakuwa umejenga mfumo wa usimamizi wa hali wa kiwango cha kitaalamu unaoshughulikia uhifadhi, uhalisia wa data, na sasisho zinazotabirika - mifumo ile ile inayotumika katika programu za uzalishaji.
+
+## Mtihani wa Kabla ya Mzungumzo
+
+[Mtihani wa kabla ya mzungumzo](https://ff-quizzes.netlify.app/web/quiz/47)
## Utangulizi
-Usimamizi wa hali ni kama mfumo wa urambazaji kwenye chombo cha Voyager – kila kitu kinapofanya kazi vizuri, huwezi hata kugundua kuwa upo. Lakini mambo yanapokwenda vibaya, inakuwa tofauti kati ya kufika anga za mbali na kupotea katika ulimwengu wa nyota. Katika ukuzaji wa wavuti, hali inawakilisha kila kitu ambacho programu yako inahitaji kukumbuka: hali ya kuingia kwa mtumiaji, data ya fomu, historia ya urambazaji, na hali za muda za kiolesura.
+Usimamizi wa hali ni kama mfumo wa urambazaji kwenye chombo cha anga cha Voyager – wakati kila kitu kinafanya kazi kwa usawa, hujali tu kwamba upo. Lakini pale mambo yanapokosea, huwa ni tofauti kati ya kufika angani interstellar na kutawanyika kupotea katika maporomoko ya anga. Katika ujenzi wa wavuti, hali inaashiria kila kitu ambacho programu yako inahitaji kukumbuka: hali ya kuingia mtumiaji, data za fomu, historia ya urambazaji, na hali za muda za kiolesura.
-Kadri programu yako ya benki imeendelea kutoka fomu rahisi ya kuingia hadi kuwa programu ya kisasa zaidi, huenda umekutana na changamoto za kawaida. Ukiboresha ukurasa, watumiaji huingia tena bila kutarajia. Ukifunga kivinjari, maendeleo yote yanapotea. Ukijaribu kutatua tatizo, unatafuta kupitia kazi nyingi zinazobadilisha data kwa njia tofauti.
+App yako ya benki ikiwa imeendelea kutoka fomu rahisi ya kuingia hadi programu tata zaidi, labda umekutana na changamoto za kawaida. Rudisha ukurasa na watumiaji hupata kuondolewa kiotomatiki. Funga kivinjari na maendeleo yote hupotea. Tatua tatizo na unatafuta kupitia kazi nyingi zinazobadilisha data ile ile kwa njia tofauti.
-Hizi si dalili za uandishi mbaya wa programu – ni changamoto za kawaida zinazotokea programu zinapofikia kiwango fulani cha ugumu. Kila msanidi programu hukutana na changamoto hizi programu zao zinapobadilika kutoka "uthibitisho wa dhana" hadi "tayari kwa uzalishaji."
+Hizi si dalili za uandishi mbaya wa msimbo – ni maumivu ya kawaida yanayotokea wakati programu zinapofikia kiwango fulani cha ugumu. Kila msanidi hujikuta na changamoto hizi wakati programu zao zinapoanza kutoka "ushahidi wa dhana" hadi "tayari kwa uzalishaji."
-Katika somo hili, tutaweka mfumo wa usimamizi wa hali ulio katikati ambao utabadilisha programu yako ya benki kuwa programu ya kuaminika na ya kitaalamu. Utajifunza kudhibiti mtiririko wa data kwa njia inayotabirika, kuhifadhi vikao vya watumiaji ipasavyo, na kuunda uzoefu laini wa mtumiaji ambao programu za wavuti za kisasa zinahitaji.
+Katika somo hili, tutatekeleza mfumo wa usimamizi wa hali uliolengwa ambao utageuza app yako ya benki kuwa programu inayotegemeka na ya kitaalamu. Utajifunza kusimamia mtiririko wa data kwa utabiri, kuhifadhi vikao vya mtumiaji ipasavyo, na kutengeneza uzoefu laini wa mtumiaji unaohitajika na programu za kisasa za wavuti.
## Mahitaji ya Awali
-Kabla ya kuingia kwenye dhana za usimamizi wa hali, unahitaji kuwa na mazingira yako ya ukuzaji yamewekwa vizuri na msingi wa programu yako ya benki uko tayari. Somo hili linajengwa moja kwa moja juu ya dhana na msimbo kutoka sehemu za awali za mfululizo huu.
+Kabla ya kuingia katika dhana za usimamizi wa hali, unahitaji kuwa na mazingira yako ya maendeleo yamesh/setup kikamilifu na msingi wa app yako ya benki uko sawa. Somo hili linajengwa moja kwa moja kwenye dhana na msimbo kutoka sehemu zilizopita za mfululizo huu.
Hakikisha una vipengele vifuatavyo tayari kabla ya kuendelea:
-**Mazingira Yanayohitajika:**
-- Kamilisha [somo la upatikanaji wa data](../3-data/README.md) - programu yako inapaswa kupakia na kuonyesha data ya akaunti kwa mafanikio
+**Mipangilio Inayohitajika:**
+- Maliza [somo la kupata data](../3-data/README.md) - app yako inapaswa kupakia na kuonyesha data za akaunti kwa mafanikio
- Sakinisha [Node.js](https://nodejs.org) kwenye mfumo wako kwa ajili ya kuendesha API ya nyuma
-- Anzisha [API ya seva](../api/README.md) kwa ndani ili kushughulikia shughuli za data ya akaunti
+- Anzisha [seva API](../api/README.md) mahali pa ndani kushughulikia operesheni za data za akaunti
-**Kujaribu Mazingira Yako:**
+**Kujifunza Mazingira Yako:**
-Thibitisha kuwa seva yako ya API inafanya kazi kwa usahihi kwa kutekeleza amri hii kwenye terminal:
+Thibitisha kuwa seva yako ya API inaendesha kwa usahihi kwa kutekeleza amri hii kwenye terminal:
```sh
curl http://localhost:5000/api
-# -> should return "Bank API v1.0.0" as a result
+# -> inapaswa kurudisha "Bank API v1.0.0" kama matokeo
```
-**Kile amri hii inafanya:**
+**Mambo haya amri hufanya:**
- **Inatuma** ombi la GET kwa seva yako ya API ya ndani
-- **Inajaribu** muunganisho na kuthibitisha kuwa seva inajibu
-- **Inarudisha** taarifa ya toleo la API ikiwa kila kitu kinafanya kazi vizuri
+- **Inajaribu** muunganisho na kuthibitisha seva inatoa majibu
+- **Inarejesha** taarifa za toleo la API ikiwa kila kitu kinafanya kazi vizuri
+
+## 🧠 Muhtasari wa Msingi wa Usimamizi wa Hali
+
+```mermaid
+mindmap
+ root((Usimamizi wa Hali))
+ Matatizo ya Sasa
+ Kupoteza Kikao
+ matatizo ya Kurejesha Ukurasa
+ Athari ya Kufunga Kivinjari
+ Matatizo ya Kurejesha Mabadiliko
+ Marekebisho yaliyogawanyika
+ Sehemu Nyingi za Mabadiliko
+ Changamoto za Kufuatilia Hitilafu
+ Tabia Isiyotabirika
+ Usafishaji Usio kamilifu
+ Matatizo ya Hali za Kutoka
+ Mtoaji wa Kumbukumbu
+ Masuala ya Usalama
+ Suluhisho za Kati
+ Kituo cha Hali Kimoja
+ Chanzo Kimoja cha Ukweli
+ Muundo Unaotabirika
+ Msingi Unaoweza Kupanuka
+ Marekebisho Dharura
+ Mifano Isiyobadilika
+ Matumizi ya Object.freeze
+ Mabadiliko Yaliyo kwenye Kazi
+ Ufuatiliaji wa Hali
+ Usimamizi wa Historia
+ Uonekano wa Hitilafu
+ Ukaguzi wa Mabadiliko
+ Mikakati ya Kuhifadhi
+ Muunganisho wa localStorage
+ Muendelevu wa Kikao
+ Uandikishaji wa JSON
+ Mlandanisho wa Kiotomatiki
+ Ubora wa Data
+ Ukaribishaji wa Server
+ Matibabu ya Data iliyochakaa
+ Uboreshaji wa Mizani
+ Uboreshaji wa Hifadhi
+ Data Ndogo
+ Kipaumbele cha Utendaji
+ Mawazo ya Usalama
+```
+**Kanuni Muhimu**: Usimamizi wa hali wa kitaalamu unaweka mizani kati ya utabiri, uhifadhi, na utendaji kazi ili kuunda uzoefu wa mtumiaji unaotegemeka unaoweza kupanuka kutoka mwingiliano rahisi hadi michakato tata ya programu.
---
-## Kutambua Masuala ya Hali ya Sasa
+## Kuchambua Tatizo la Hali ya Sasa
-Kama Sherlock Holmes akichunguza eneo la uhalifu, tunahitaji kuelewa kinachotokea katika utekelezaji wetu wa sasa kabla ya kutatua fumbo la vikao vya watumiaji vinavyopotea.
+Kama Sherlock Holmes akichunguza eneo la uhalifu, tunahitaji kuelewa hasa kinachotokea katika utekelezaji wetu wa sasa kabla ya kutatua fumbo la kupotea kwa vikao vya mtumiaji.
-Tufanye jaribio rahisi linaloonyesha changamoto za usimamizi wa hali:
+Tufanye jaribio rahisi linaloonyesha changamoto za msingi za usimamizi wa hali:
-**🧪 Jaribu Uchunguzi Huu:**
-1. Ingia kwenye programu yako ya benki na nenda kwenye dashibodi
-2. Boresha ukurasa wa kivinjari
-3. Angalia kinachotokea kwa hali yako ya kuingia
+**🧪 Jaribu Hili la Uchunguzi:**
+1. Ingia kwenye app yako ya benki na nenda kwenye dashibodi
+2. Rudisha ukurasa wa kivinjari
+3. Tazama kinachotokea kwenye hali yako ya kuingia
-Ikiwa unarudishwa kwenye skrini ya kuingia, umegundua tatizo la kawaida la uhifadhi wa hali. Tabia hii hutokea kwa sababu utekelezaji wetu wa sasa huhifadhi data ya mtumiaji kwenye vigezo vya JavaScript vinavyofutwa kila ukurasa unapobadilishwa.
+Kama unarudiwa tena kwenye skrini ya kuingia, umegundua tatizo la uhifadhi wa hali. Tabia hii hutokea kwa sababu utekelezaji wetu wa sasa huhifadhi data za mtumiaji kwenye vigezo vya JavaScript vinavyosafishwa kila mara ukurasa unaporudishwa.
**Matatizo ya Utekelezaji wa Sasa:**
-Kigezo rahisi cha `account` kutoka [somo letu la awali](../3-data/README.md) kinazalisha matatizo matatu makubwa yanayoathiri uzoefu wa mtumiaji na utunzaji wa msimbo:
+Kigezo rahisi cha `account` kutoka kwa [somo letu la awali](../3-data/README.md) kinasababisha matatizo makubwa matatu yanayoathiri uzoefu wa mtumiaji na uimara wa msimbo:
| Tatizo | Sababu ya Kiufundi | Athari kwa Mtumiaji |
|---------|--------|----------------|
-| **Upotevu wa Kikao** | Kuboresha ukurasa hufuta vigezo vya JavaScript | Watumiaji wanapaswa kuingia mara kwa mara |
-| **Mabadiliko Yaliyotawanyika** | Kazi nyingi hubadilisha hali moja kwa moja | Utatuzi wa matatizo unakuwa mgumu zaidi |
-| **Usafishaji Usio Kamili** | Kuondoka hakufuti marejeleo yote ya hali | Wasiwasi wa usalama na faragha |
-
-**Changamoto ya Kimuundo:**
-
-Kama muundo wa sehemu za Titanic ulioonekana kuwa thabiti hadi sehemu nyingi zilipojaa maji kwa wakati mmoja, kutatua matatizo haya moja moja hakutashughulikia tatizo la kimuundo lililopo. Tunahitaji suluhisho la kina la usimamizi wa hali.
-
-> 💡 **Tunajaribu kufanikisha nini hapa?**
-
-[Usimamizi wa hali](https://en.wikipedia.org/wiki/State_management) kimsingi ni kuhusu kutatua mafumbo mawili ya msingi:
-
-1. **Data Yangu Iko Wapi?**: Kufuatilia taarifa tuliyonayo na inatoka wapi
-2. **Je, Kila Mtu Yuko Ukurasa Mmoja?**: Kuhakikisha kile watumiaji wanachoona kinawiana na kinachotokea
-
-**Mpango Wetu wa Mchezo:**
-
-Badala ya kuzunguka bila mwelekeo, tutaunda mfumo wa **usimamizi wa hali ulio katikati**. Fikiria kama kuwa na mtu mmoja aliyeandaliwa vizuri anayesimamia mambo yote muhimu:
-
-
-
+| **Kupotea kwa Kikao** | Kurudisha ukurasa kunafuta vigezo vya JavaScript | Watumiaji wanapaswa kuingia mara kwa mara |
+| **Sasisho Zilizopangwa Kwenye Sehemu Zenye Tofauti** | Kazi nyingi hubadilisha hali moja kwa moja | Kutatua matatizo kunazidi kuwa ngumu |
+| **Usafishaji Mfupi** | Kuondoka haafuta marejeleo yote ya hali | Hatari za usalama na faragha |
+
+**Changamoto ya Miundo:**
+
+Kama muundo wa sehemu za Titanic ulioonekana imara hadi sehemu nyingi kuzama kwa pamoja, kurekebisha matatizo haya moja baada ya nyingine haitaondoa tatizo la msingi la usanifu. Tunahitaji suluhisho kamili la usimamizi wa hali.
+
+> 💡 **Tunajaribu kufanikisha nini hasa hapa?**
+
+[Usimamizi wa hali](https://en.wikipedia.org/wiki/State_management) ni kweli kuhusu kutatua fumbo mbili za msingi:
+
+1. **Data Yangu Iko Wapi?**: Kufuatilia taarifa tunazozipata na chanzo chake
+2. **Je, Wote Wako na Taarifa Sawia?**: Kuhakikisha kile watumiaji wanaona kinaendana na kinachotokea
+
+**Mpango wetu wa Kiongozi:**
+
+Badala ya kuzunguka kwa kutafuta mwishowe, tutaunda **mfumo wa usimamizi wa hali uliolengwa katikati**. Fikiria kama mtu mmoja aliyepangwa vizuri anayehudumia vitu vyote muhimu:
+
+
+
+```mermaid
+flowchart TD
+ A[Hatua ya Mtumiaji] --> B[Msimamizi wa Tukio]
+ B --> C[Kazi ya updateState]
+ C --> D{Uhakiki wa Hali}
+ D -->|Halali| E[Tengeneza Hali Mpya]
+ D -->|Sio Halali| F[Usimamizi wa Makosa]
+ E --> G[Object.freeze]
+ G --> H[Update localStorage]
+ H --> I[Anzisha Sasisho la UI]
+ I --> J[Mtumiaji Anaona Mabadiliko]
+ F --> K[Mtumiaji Anaona Kosa]
+
+ subgraph "Tabaka la Usimamizi wa Hali"
+ C
+ E
+ G
+ end
+
+ subgraph "Tabaka la Uhifadhi"
+ H
+ L[localStorage]
+ H -.-> L
+ end
+```
**Kuelewa mtiririko huu wa data:**
-- **Unakusanya** hali yote ya programu katika eneo moja
-- **Unapanga** mabadiliko yote ya hali kupitia kazi zilizodhibitiwa
-- **Unahakikisha** UI inabaki kulingana na hali ya sasa
-- **Unatoa** muundo wazi na unaotabirika wa usimamizi wa data
+- **Unahusisha** hali zote za programu mahali pamoja
+- **Pitia** mabadiliko yote ya hali kupitia kazi za kidhibitiwa
+- **Hakikisha** UI inabaki sambamba na hali ya sasa
+- **Toa** muundo wazi, unaoweza kutabirika wa usimamizi wa data
-> 💡 **Ujuzi wa Kitaalamu**: Somo hili linazingatia dhana za msingi. Kwa programu ngumu, maktaba kama [Redux](https://redux.js.org) hutoa vipengele vya hali ya juu vya usimamizi wa hali. Kuelewa kanuni hizi za msingi kutakusaidia kumudu maktaba yoyote ya usimamizi wa hali.
+> 💡 **Maarifa ya Kitaalamu**: Somo hili linazingatia dhana za msingi. Kwa programu changamano, maktaba kama [Redux](https://redux.js.org) hutoa vipengele vya juu vya usimamizi wa hali. Kuelewa misingi hii kutakusaidia kumiliki maktaba yoyote ya usimamizi wa hali.
-> ⚠️ **Mada ya Juu**: Hatutashughulikia masasisho ya UI yanayotokea moja kwa moja kutokana na mabadiliko ya hali, kwani hili linahusisha dhana za [Programu ya Kijibu](https://en.wikipedia.org/wiki/Reactive_programming). Fikiria hili kama hatua nzuri inayofuata katika safari yako ya kujifunza!
+> ⚠️ **Mada ya Juu**: Hatujajadili sasisho la kiotomatiki la UI linapotokea kwa mabadiliko ya hali, kwa kuwa hili linahusisha dhana za [Programming ya Kusikika](https://en.wikipedia.org/wiki/Reactive_programming). Dhana hii tena ni hatua nzuri kwa safari yako ya kujifunza!
-### Kazi: Kuweka Muundo wa Hali Katikati
+### Kazi: Kuweka Mfumo wa Hali Katikati
-Tuanzishe mabadiliko ya usimamizi wa hali uliotawanyika kuwa mfumo ulio katikati. Hatua hii ya kwanza inaweka msingi wa maboresho yote yanayofuata.
+Tuanze kubadilisha usimamizi wetu wa hali uliotawanyika kuwa mfumo ulioko katikati. Hatua hii ya kwanza inaweka msingi kwa maboresho yote yatakayofuata.
-**Hatua ya 1: Unda Kitu cha Hali Katikati**
+**Hatua ya 1: Unda Kitu cha Hali Kati**
-Badilisha tamko rahisi la `account`:
+Badilisha tangazo rahisi la `account`:
```js
let account = null;
```
-Na kitu cha hali kilichopangwa:
+Kwa kitu cha hali chenye muundo:
```js
let state = {
@@ -120,80 +244,112 @@ let state = {
};
```
-**Kwa nini mabadiliko haya ni muhimu:**
-- **Unakusanya** data yote ya programu katika eneo moja
-- **Unatayarisha** muundo wa kuongeza mali zaidi za hali baadaye
-- **Unaunda** mpaka wazi kati ya hali na vigezo vingine
-- **Unaanzisha** muundo unaokua kadri programu yako inavyopanuka
+**Hii ni kwa nini mabadiliko haya ni muhimu:**
+- **Unahusisha** data zote za programu mahali pamoja
+- **Huandaa** muundo wa kuongeza mali zaidi baadaye
+- **Huunda** mpaka wazi kati ya hali na vigezo vingine
+- **Huanzisha** muundo unaopanuka kadri app yako inavyoendelea
-**Hatua ya 2: Sasisha Mifumo ya Ufikiaji wa Hali**
+**Hatua ya 2: Sasisha Mifumo ya Kufikia Hali**
Sasisha kazi zako kutumia muundo mpya wa hali:
-**Katika kazi za `register()` na `login()`**, badilisha:
+**Katika kazi `register()` na `login()`**, badilisha:
```js
account = ...
```
-Na:
+Kwa:
```js
state.account = ...
```
-**Katika kazi ya `updateDashboard()`**, ongeza mstari huu juu:
+**Katika kazi `updateDashboard()`**, ongeza mstari huu juu:
```js
const account = state.account;
```
-**Kile masasisho haya yanayofanikisha:**
-- **Yanaweka** utendaji uliopo huku yakiboresha muundo
-- **Yanatayarisha** msimbo wako kwa usimamizi wa hali wa kisasa zaidi
-- **Yanaanzisha** mifumo thabiti ya kufikia data ya hali
-- **Yanaweka** msingi wa masasisho ya hali yaliyo katikati
+**Haya maboresho yanayafanya nini:**
+- **Hudumisha** utendaji uliopo huku hutangaza muundo
+- **Huandaa** msimbo wako kwa usimamizi wa hali wenye ustadi zaidi
+- **Huunda** mifumo thabiti ya kufikia data ya hali
+- **Huanzisha** msingi wa sasisho za hali zilizo na lengo katikati
+
+> 💡 **Kumbuka**: Marekebisho haya hayatatatua matatizo yetu mara moja, bali huweka msingi muhimu kwa maboresho makubwa yajayo!
-> 💡 **Kumbuka**: Urekebishaji huu hauwezi kutatua matatizo yetu mara moja, lakini unaweka msingi muhimu kwa maboresho yenye nguvu yanayokuja!
+### 🎯 Ukaguzi wa Kielimu: Kanuni za Kuweka Katikati
-## Kutekeleza Masasisho ya Hali Yaliyo Dhibitiwa
+**Pumzika na Fikiria**: Umeweka msingi wa usimamizi wa hali ulioko katikati. Hii ni uamuzi muhimu wa usanifu.
-Kadri hali yetu inavyokusanywa, hatua inayofuata inahusisha kuanzisha mifumo iliyodhibitiwa ya mabadiliko ya data. Mbinu hii inahakikisha mabadiliko ya hali yanayotabirika na utatuzi rahisi wa matatizo.
+**Uhakiki wa Haraka:**
+- Je, unaweza kueleza kwa nini kuweka hali katikati kwenye kitu kimoja ni bora zaidi kuliko vigezo vilivyoenea?
+- Kitatokea nini kama umetah forget kusasisha kazi kutumia `state.account`?
+- Muundo huu hutayarisha vipi msimbo wako kwa vipengele vya hali vya juu?
-Kanuni ya msingi inafanana na udhibiti wa trafiki ya anga: badala ya kuruhusu kazi nyingi kubadilisha hali kwa uhuru, tutapanga mabadiliko yote kupitia kazi moja iliyodhibitiwa. Muundo huu unatoa usimamizi wazi wa wakati na jinsi data inavyobadilika.
+**Uhusiano wa Kisheria**: Muundo wa katikati uliyojifunza ni msingi wa mifumo ya kisasa kama Redux, Vuex, na React Context. Unajenga ile fikra ya usanifu inayotumika kwenye programu kubwa.
-**Usimamizi wa Hali Isiyobadilika:**
+**Swali la Changamoto**: Kama unahitaji kuongeza mapendeleo ya mtumiaji (mandhari, lugha), ungeongeza wapi kwenye muundo wa hali? Hii ingeenea vipi?
-Tutachukulia kitu chetu cha `state` kama [*kisichobadilika*](https://en.wikipedia.org/wiki/Immutable_object), ikimaanisha hatutabadilisha moja kwa moja. Badala yake, kila mabadiliko yataunda kitu kipya cha hali na data iliyosasishwa.
+## Kutekeleza Sasisho za Hali za Kudhibitiwa
-Ingawa mbinu hii inaweza kuonekana kuwa isiyo na ufanisi mwanzoni ikilinganishwa na mabadiliko ya moja kwa moja, inatoa faida kubwa kwa utatuzi wa matatizo, upimaji, na kudumisha utabiri wa programu.
+Hali yetu ikiwa katikati, hatua inayofuata ni kuunda mbinu za kudhibiti mabadiliko ya data. Njia hii huhakikisha mabadiliko ya hali yanayoweza kutabirika na rahisi kuchunguza tatizo.
+
+Kanuni kuu ni kama ukaguzi wa usafiri wa anga: badala ya kuruhusu kazi nyingi kubadilisha hali peke yake, tutapeleka mabadiliko yote kupitia kazi moja iliyodhibitiwa. Muundo huu hutoa usimamizi wazi wakati na jinsi data inavyobadilika.
+
+**Usimamizi wa Hali Isiyobadilika (Immutable):**
+
+Tutachukulia kitu cha `state` kama [*kisichobadilika*](https://en.wikipedia.org/wiki/Immutable_object), ikimaanisha hatubadilishi moja kwa moja. Badala yake, kila mabadiliko huunda kitu kipya cha hali chenye data iliyosasishwa.
+
+Ingawa njia hii inaweza kuonekana isiyo na ufanisi ikilinganishwa na mabadiliko ya moja kwa moja, inatoa faida kubwa katika kutatua matatizo, kufanya majaribio, na kudumisha utabiri wa programu.
**Faida za usimamizi wa hali isiyobadilika:**
| Faida | Maelezo | Athari |
|---------|-------------|--------|
-| **Utabiri** | Mabadiliko hutokea tu kupitia kazi zilizodhibitiwa | Rahisi kutatua matatizo na kupima |
-| **Ufuatiliaji wa Historia** | Kila mabadiliko ya hali huunda kitu kipya | Inawezesha utendakazi wa kurudisha/kufanya upya |
-| **Kuzuia Athari za Pembeni** | Hakuna mabadiliko ya bahati mbaya | Huzuia hitilafu za ajabu |
-| **Uboreshaji wa Utendaji** | Rahisi kugundua wakati hali imebadilika | Inawezesha masasisho ya UI yenye ufanisi |
+| **Utabiri** | Mabadiliko hutokea tu kupitia kazi za kudhibitiwa | Rahisi kutatua matatizo na kufanya majaribio |
+| **Ufuatiliaji wa Historia** | Kila mabadiliko wa hali huunda kitu kipya | Inawezesha kipengele cha kubatilisha/kurudisha (undo/redo) |
+| **Kuzuia Athari za Pembeni** | Hakuna mabadiliko ya bahati nasibu | Huzuia mende zisizojulikana |
+| **Uboreshaji wa Utendaji** | Rahisi kugundua wakati hali hubadilika kweli | Inawezesha sasisho la UI kwa ufanisi |
-**Usimamizi wa Hali Isiyobadilika kwa JavaScript na `Object.freeze()`:**
+**Ubadilishaji wa JavaScript kwa `Object.freeze()`:**
-JavaScript inatoa [`Object.freeze()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) kuzuia mabadiliko ya vitu:
+JavaScript hutoa [`Object.freeze()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) ili kuzuia mabadiliko ya kitu:
```js
const immutableState = Object.freeze({ account: userData });
-// Any attempt to modify immutableState will throw an error
+// Jaribio lolote la kubadilisha immutableState litasababisha kosa
```
-**Kufafanua kinachotokea hapa:**
-- **Inazuia** uwekaji wa mali moja kwa moja au ufutaji
-- **Inatupa** makosa ikiwa majaribio ya mabadiliko yanafanywa
+**Kuvunja kile kinachotokea hapa:**
+- **Huzuia** kuweka au kufuta mali moja kwa moja
+- **Inatupa** makosa ikiwa jaribio la kuibadilisha linatokea
- **Inahakikisha** mabadiliko ya hali lazima yapitie kazi zilizodhibitiwa
-- **Inaunda** mkataba wazi wa jinsi hali inavyoweza kusasishwa
-
-> 💡 **Uchambuzi wa Kina**: Jifunze kuhusu tofauti kati ya vitu vya *juu juu* na *vilivyo ndani kabisa* visivyobadilika katika [mdokumentari ya MDN](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze#What_is_shallow_freeze). Kuelewa tofauti hii ni muhimu kwa miundo ya hali ngumu.
-
+- **Inatengeneza** makubaliano wazi ya jinsi hali inaweza kusasishwa
+
+> 💡 **Kujifunza Zaidi**: Jifunze tofauti kati ya vitu *isipozidi* na *isipozidi kwa kina* katika [nyaraka za MDN](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze#What_is_shallow_freeze). Kuelewa tofauti hii ni muhimu kwa miundo ya hali tata.
+
+```mermaid
+stateDiagram-v2
+ [*] --> StateV1: Hali ya Awali
+ StateV1 --> StateV2: updateState('account', newData)
+ StateV2 --> StateV3: updateState('account', anotherUpdate)
+ StateV3 --> StateV4: updateState('preferences', userSettings)
+
+ note right of StateV1
+ Object.freeze()
+ Haibadiliki
+ Inaweza kufuatiliwa
+ end note
+
+ note right of StateV2
+ Kitu kipya kimeundwa
+ Hali ya awali imehifadhiwa
+ Mabadiliko yanayoweza kutabirika
+ end note
+```
### Kazi
-Tuunde kazi mpya ya `updateState()`:
+Tundike kazi mpya ya `updateState()`:
```js
function updateState(property, newData) {
@@ -204,9 +360,9 @@ function updateState(property, newData) {
}
```
-Katika kazi hii, tunaunda kitu kipya cha hali na kunakili data kutoka hali ya awali kwa kutumia [*spread (`...`) operator*](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/Spread_syntax#Spread_in_object_literals). Kisha tunabadilisha mali fulani ya kitu cha hali na data mpya kwa kutumia [bracket notation](https://developer.mozilla.org/docs/Web/JavaScript/Guide/Working_with_Objects#Objects_and_properties) `[property]` kwa uwekaji. Hatimaye, tunafungia kitu ili kuzuia mabadiliko kwa kutumia `Object.freeze()`. Kwa sasa tuna mali ya `account` tu iliyohifadhiwa katika hali, lakini kwa mbinu hii unaweza kuongeza mali nyingi unavyohitaji katika hali.
+Katika kazi hii, tunaunda kitu kipya cha hali na kunakili data kutoka hali ya awali kwa kutumia [*operator ya spread (`...`)*](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/Spread_syntax#Spread_in_object_literals). Kisha tunabadilisha mali fulani ya kitu cha hali na data mpya kwa kutumia alama za mabano `[property]` kwa ajili ya kuweka. Hatimaye, tunalazimisha kitu hicho kwa kutumia `Object.freeze()`. Kwa sasa tunayo property `account` tu huhifadhiwa katika hali, lakini kwa njia hii unaweza kuongeza mali nyingi kama unavyohitaji.
-Tutasasisha pia uanzishaji wa `state` kuhakikisha hali ya awali imefungwa pia:
+Pia tutajisahihisha kuanzisha kwa `state` ili kuhakikisha hali ya mwanzo inawekwa imara:
```js
let state = Object.freeze({
@@ -214,19 +370,19 @@ let state = Object.freeze({
});
```
-Baada ya hapo, sasisha kazi ya `register` kwa kubadilisha uwekaji wa `state.account = result;` na:
+Baada ya hapo, sasisha kazi ya `register` kwa kubadilisha `state.account = result;` na:
```js
updateState('account', result);
```
-Fanya vivyo hivyo na kazi ya `login`, ukibadilisha `state.account = data;` na:
+Fanya vivyo hivyo kwa kazi ya `login`, badilisha `state.account = data;` na:
```js
updateState('account', data);
```
-Sasa tutatumia fursa ya kutatua tatizo la data ya akaunti kutosafishwa mtumiaji anapobofya *Logout*.
+Sasa tutatumia fursa hii kurekebisha tatizo la data za akaunti kutafutwa wakati mtumiaji anabonyeza *Logout*.
Unda kazi mpya `logout()`:
@@ -237,105 +393,123 @@ function logout() {
}
```
-Katika `updateDashboard()`, badilisha uelekezaji `return navigate('/login');` na `return logout()`;
+Katika `updateDashboard()`, badilisha urejeshaji `return navigate('/login');` na `return logout()`;
-Jaribu kusajili akaunti mpya, kutoka na kuingia tena ili kuhakikisha kila kitu bado kinafanya kazi vizuri.
+Jaribu kuunda akaunti mpya, kutoka na kuingia tena ili kuhakiki kuwa kila kitu bado kinafanya kazi ipasavyo.
-> Kidokezo: unaweza kuangalia mabadiliko yote ya hali kwa kuongeza `console.log(state)` chini ya `updateState()` na kufungua console katika zana za ukuzaji za kivinjari chako.
+> Vidokezo: unaweza kutazama mabadiliko yote ya hali kwa kuongeza `console.log(state)` chini ya `updateState()` na kufungua console katika vifaa vya maendeleo vya kivinjari chako.
## Kutekeleza Uhifadhi wa Data
-Tatizo la upotevu wa kikao tulilobaini awali linahitaji suluhisho la uhifadhi linalodumisha hali ya mtumiaji katika vikao vya kivinjari. Hii inabadilisha programu yetu kutoka uzoefu wa muda hadi kuwa zana ya kuaminika na ya kitaalamu.
+Tatizo la kupotea kwa kikao tuliloligundua awali linahitaji suluhisho la uhifadhi unaoendelea unaoendeleza hali za mtumiaji kati ya vikao vya kivinjari. Hii hubadilisha programu yetu kutoka uzoefu wa muda mfupi hadi chombo kinachotegemewa na kitaalamu.
-Fikiria jinsi saa za atomiki zinavyodumisha muda sahihi hata wakati wa kukatika kwa umeme kwa kuhifadhi hali muhimu katika kumbukumbu isiyopotea. Vivyo hivyo, programu za wavuti zinahitaji mifumo ya uhifadhi wa kudumu ili kuhifadhi data muhimu ya mtumiaji katika vikao vya kivinjari na ubadilishaji wa ukurasa.
+Fikiria jinsi saa za atomiki zinavyoendelea kuonyesha saa sahihi hata wakati wa kukatika kwa nguvu kwa umeme kwa kuhifadhi hali muhimu katika kumbukumbu isiyohamishika. Vivyo hivyo, programu za wavuti zinahitaji mbinu za uhifadhi endelevu ili kuhifadhi data muhimu za mtumiaji kati ya vikao vya kivinjari na kurudisha ukurasa.
-**Maswali ya Kistratejia kwa Uhifadhi wa Data:**
+**Maswali ya Mkakati kwa Uhifadhi Data:**
Kabla ya kutekeleza uhifadhi, fikiria mambo haya muhimu:
-| Swali | Muktadha wa Programu ya Benki | Athari ya Uamuzi |
+| Swali | Muktadha wa App ya Benki | Athari ya Uamuzi |
|----------|-------------------|----------------|
-| **Je, data ni nyeti?** | Mizani ya akaunti, historia ya miamala | Chagua mbinu salama za uhifadhi |
-| **Inapaswa kudumu kwa muda gani?** | Hali ya kuingia vs. mapendeleo ya muda ya UI | Chagua muda wa uhifadhi unaofaa |
-| **Je, seva inaihitaji?** | Tokeni za uthibitishaji vs. mipangilio ya UI | Amua mahitaji ya kushiriki |
+| **Je, data ni nyeti?** | Salio la akaunti, historia ya muamala | Chagua mbinu za usalama za kuhifadhi |
+| **Inapaswa kudumu kwa muda gani?** | Hali ya kuingia vs. mapendeleo ya muda ya UI | Chagua muda unaofaa wa kuhifadhi |
+| **Je, server inahitaji?** | Vitambulisho vya uthibitishaji vs. mipangilio ya UI | Amua mahitaji ya kushirikiana |
-**Chaguo za Uhifadhi wa Kivinjari:**
+**Chaguzi za Uhifadhi wa Kivinjari:**
-Vivinjari vya kisasa vinatoa mifumo kadhaa ya uhifadhi, kila moja imeundwa kwa matumizi tofauti:
+Vivinjari vya kisasa vina taratibu mbalimbali za kuhifadhi, kila moja imetengenezwa kwa matumizi tofauti:
-**API za Uhifadhi wa Msingi:**
+**API Kuu za Uhifadhi:**
-1. **[`localStorage`](https://developer.mozilla.org/docs/Web/API/Window/localStorage)**: Uhifadhi wa [Key/Value](https://en.wikipedia.org/wiki/Key%E2%80%93value_database) wa kudumu
- - **Hudumu** data katika vikao vya kivinjari bila kikomo
- - **Husalia** hata kivinjari kinapofungwa na kompyuta kuanzishwa upya
- - **Imefungwa** kwa kikoa maalum cha tovuti
- - **Inafaa** kwa mapendeleo ya mtumiaji na hali za kuingia
+1. **[`localStorage`](https://developer.mozilla.org/docs/Web/API/Window/localStorage)**: Uhifadhi wa kudumu wa [Key/Value](https://en.wikipedia.org/wiki/Key%E2%80%93value_database)
+ - **Hudumu** data kati ya vikao vya kivinjari bila kikomo
+ - **Huanguka** mara kivinjari kinapoanzishwa upya na kompyuta kuwa boot
+ - **Inahudumia** eneo maalum la tovuti
+ - **Inafaa** kwa mapendeleo ya mtumiaji na hali za kujisajili
-2. **[`sessionStorage`](https://developer.mozilla.org/docs/Web/API/Window/sessionStorage)**: Uhifadhi wa kikao cha muda
- - **Hufanya kazi** sawa na localStorage wakati wa vikao hai
- - **Hufutwa** kiotomatiki kivinjari kinapofungwa
- - **Inafaa** kwa data ya muda ambayo haipaswi kudumu
+2. **[`sessionStorage`](https://developer.mozilla.org/docs/Web/API/Window/sessionStorage)**: Uhifadhi wa muda wa kikao
+ - **Hufanya kazi** kama vile localStorage wakati wa vikao vinavyotumika
+ - **Hufuta** moja kwa moja wakati kichupo cha kivinjari kinapofungwa
+ - **Inafaa** kwa data za muda ambazo hazipaswi kuhifadhiwa
-3. **[HTTP Cookies](https://developer.mozilla.org/docs/Web/HTTP/Cookies)**: Uhifadhi unaoshirikiwa na seva
- - **Hutumwa** kiotomatiki na kila ombi la seva
- - **Inafaa** kwa [uthibitishaji](https://en.wikipedia.org/wiki/Authentication) wa tokeni
- - **Imewekewa mipaka** kwa ukubwa na inaweza kuathiri utendaji
+3. **[HTTP Cookies](https://developer.mozilla.org/docs/Web/HTTP/Cookies)**: Uhifadhi wa kushirikiana na server
+ - **Hutumwa moja kwa moja** na kila ombi la server
+ - **Inafaa** kwa vitambulisho vya [uthibitishaji](https://en.wikipedia.org/wiki/Authentication)
+ - **Ina kikomo** ukubwa na inaweza kuathiri utendaji
-**Mahitaji ya Usawazishaji wa Data:**
+**Hitaji la Usanifuaji wa Data:**
Zote `localStorage` na `sessionStorage` huhifadhi tu [nyuzi](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String):
```js
-// Convert objects to JSON strings for storage
+// Geuza vitu kuwa mizstrings ya JSON kwa ajili ya uhifadhi
const accountData = { user: 'john', balance: 150 };
localStorage.setItem('account', JSON.stringify(accountData));
-// Parse JSON strings back to objects when retrieving
+// Tafsiri mizstrings ya JSON kurudi kuwa vitu wakati wa kuondoa
const savedAccount = JSON.parse(localStorage.getItem('account'));
```
-**Kuelewa usawazishaji:**
+**Kuelewa usanifuaji:**
- **Hubadilisha** vitu vya JavaScript kuwa nyuzi za JSON kwa kutumia [`JSON.stringify()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)
-- **Hujenga upya** vitu kutoka JSON kwa kutumia [`JSON.parse()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse)
-- **Hushughulikia** vitu vilivyopangwa kwa kina na safu kiotomatiki
-- **Hushindwa** kwa kazi, thamani zisizoelezwa, na marejeleo ya mzunguko
-> 💡 **Chaguo la Juu**: Kwa programu ngumu za nje ya mtandao zenye hifadhidata kubwa, fikiria kutumia [`IndexedDB` API](https://developer.mozilla.org/docs/Web/API/IndexedDB_API). Inatoa hifadhidata kamili upande wa mteja lakini inahitaji utekelezaji tata zaidi.
-
-### Kazi: Tekeleza Uhifadhi wa localStorage
+- **Huunda upya** vitu kutoka JSON kwa kutumia [`JSON.parse()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse)
+- **Hushughulikia** vitu tata vilivyopangwa na orodha moja kwa moja
+- **Hushindwa** kwenye kazi, thamani zisizojulikana, na marejeleo ya duara
+
+> 💡 **Uchaguo wa Kipekee**: Kwa programu tata zisizo mtandaoni zilizo na seti kubwa za data, angalia [`IndexedDB` API](https://developer.mozilla.org/docs/Web/API/IndexedDB_API). Inatoa hifadhidata kamili upande wa mteja lakini inahitaji utekelezaji tata zaidi.
+
+```mermaid
+quadrantChart
+ title Chaguzi za Hifadhi ya Kivinjari
+ x-axis Ugumu Mdogo --> Ugumu Mkubwa
+ y-axis Muda Mfupi --> Muda Mrefu
+
+ quadrant-1 Zana za Kitaalamu
+ quadrant-2 Uhifadhi Rahisi
+ quadrant-3 Hifadhi ya Muda
+ quadrant-4 Mifumo ya Juu
+
+ localStorage: [0.3, 0.8]
+ sessionStorage: [0.2, 0.2]
+ HTTP Cookies: [0.6, 0.7]
+ IndexedDB: [0.9, 0.9]
+ Memory Variables: [0.1, 0.1]
+```
+### Kazi: Tekeleza Kudumu kwa localStorage
-Tutaweka uhifadhi wa kudumu ili watumiaji wabaki wameingia hadi watakapoamua kujiondoa. Tutatumia `localStorage` kuhifadhi data ya akaunti kati ya vikao vya kivinjari.
+Tuwekee uhifadhi wa kudumu ili watumiaji wabaki wameingia hadi waondoke waziwazi. Tutatumia `localStorage` kuhifadhi data za akaunti kati ya vikao vya kivinjari.
-**Hatua ya 1: Fafanua Usanidi wa Uhifadhi**
+**Hatua 1: Eleza Mipangilio ya Uhifadhi**
```js
const storageKey = 'savedAccount';
```
-**Kile ambacho kigezo hiki kinatoa:**
-- **Hutengeneza** kitambulisho thabiti kwa data yetu iliyohifadhiwa
-- **Huzuia** makosa ya herufi katika marejeleo ya funguo za uhifadhi
-- **Hufanya** iwe rahisi kubadilisha ufunguo wa uhifadhi ikiwa inahitajika
-- **Hufuata** mbinu bora za msimbo unaoweza kudumishwa
+**Hili linalotolewa na tabia hii:**
+- **Huzima** kitambulisho thabiti kwa data yetu iliyohifadhiwa
+- **Huzuia** makosa ya tahajia katika marejeleo ya ufunguo wa kuhifadhi
+- **Hurahisisha** kubadilisha ufunguo wa kuhifadhi inapohitajika
+- **Hufuata** mbinu bora za kuandika msimbo unaotunzwa
-**Hatua ya 2: Ongeza Uhifadhi wa Kiotomatiki**
+**Hatua 2: Ongeza Kudumu Moja kwa Moja**
-Ongeza mstari huu mwishoni mwa kazi ya `updateState()`:
+Ongeza mstari huu mwishoni mwa kazi `updateState()`:
```js
localStorage.setItem(storageKey, JSON.stringify(state.account));
```
-**Kufafanua kinachotokea hapa:**
-- **Hubadilisha** kitu cha akaunti kuwa kamba ya JSON kwa uhifadhi
-- **Huokoa** data kwa kutumia ufunguo wetu thabiti wa uhifadhi
-- **Hutekeleza** kiotomatiki kila mabadiliko ya hali yanapotokea
-- **Hakikisha** data iliyohifadhiwa inalingana na hali ya sasa
+**Kuvunja kile kinachotokea hapa:**
+- **Hubadilisha** kitu cha akaunti kuwa nyuzi ya JSON kwa kuhifadhi
+- **Huinua** data kwa kutumia ufunguo wetu wa kuhifadhi thabiti
+- **Hutekelezwa** moja kwa moja kila mara hali inapo badilika
+- **Hakikisha** data iliyohifadhiwa inaendana kila wakati na hali ya sasa
-> 💡 **Faida ya Usanifu**: Kwa sababu tulizingatia mabadiliko yote ya hali kupitia `updateState()`, kuongeza uhifadhi kulihitaji mstari mmoja tu wa msimbo. Hii inaonyesha nguvu ya maamuzi mazuri ya usanifu!
+> 💡 **Faida ya Mimariko**: Kwa sababu tulilenga masasisho yote ya hali kupitia `updateState()`, kuongeza kudumu kulihitaji mstari mmoja tu wa msimbo. Hii inaonyesha nguvu ya maamuzi mazuri ya miundo!
-**Hatua ya 3: Rudisha Hali Wakati Programu Inapopakia**
+**Hatua 3: Rudisha Hali Unapoanzisha App**
-Tengeneza kazi ya uanzishaji ili kurudisha data iliyohifadhiwa:
+Tengeneza kazi ya kuanzisha ili kurudisha data iliyohifadhiwa:
```js
function init() {
@@ -344,7 +518,7 @@ function init() {
updateState('account', JSON.parse(savedAccount));
}
- // Our previous initialization code
+ // Msimbo wetu wa awali wa kuanzisha
window.onpopstate = () => updateRoute();
updateRoute();
}
@@ -352,49 +526,63 @@ function init() {
init();
```
-**Kuelewa mchakato wa uanzishaji:**
-- **Hurejesha** data yoyote ya akaunti iliyohifadhiwa awali kutoka localStorage
-- **Huchambua** kamba ya JSON kurudi kuwa kitu cha JavaScript
-- **Husasa** hali kwa kutumia kazi yetu ya kusasisha iliyodhibitiwa
-- **Hurudisha** kikao cha mtumiaji kiotomatiki wakati ukurasa unapopakia
-- **Hutekeleza** kabla ya masasisho ya njia ili kuhakikisha hali inapatikana
+**Kuelewa mchakato wa kuanzisha:**
+- **Inapokea** data yoyote ya akaunti iliyohifadhiwa awali kutoka localStorage
+- **Inatambua** nyuzi za JSON kurudisha tena kuwa kitu cha JavaScript
+- **Inasasisha** hali kwa kutumia kazi yetu ya kusawazisha
+- **Inarejesha** kikao cha mtumiaji moja kwa moja anapopakua ukurasa
+- **Inatekelezwa** kabla ya masasisho ya njia ili kuhakikisha hali inapatikana
-**Hatua ya 4: Boresha Njia ya Kawaida**
+**Hatua 4: Boresha Njia ya Chaguo-msingi**
-Sasisha njia ya kawaida ili kutumia uhifadhi:
+Sasisha njia ya chaguo-msingi ili kutumia faida ya kudumu:
Katika `updateRoute()`, badilisha:
```js
-// Replace: return navigate('/login');
+// Badilisha: return navigate('/login');
return navigate('/dashboard');
```
-**Kwa nini mabadiliko haya yana mantiki:**
-- **Hutumia** mfumo wetu mpya wa uhifadhi kwa ufanisi
-- **Huruhusu** dashibodi kushughulikia ukaguzi wa uthibitisho
-- **Huelekeza** kiotomatiki kwenye kuingia ikiwa hakuna kikao kilichohifadhiwa
-- **Hutengeneza** uzoefu wa mtumiaji usio na mshono
+**Kwa nini mabadiliko haya yanaeleweka:**
+- **Yatumia** mfumo wetu mpya wa kudumu kwa ufanisi
+- **Inaruhusu** dashibodi kushughulikia ukaguzi wa uthibitishaji
+- **Huelekeza** kwa kuingia moja kwa moja kama hakuna kikao kilichohifadhiwa
+- **Inaunda** uzoefu mzuri zaidi kwa mtumiaji
-**Kupima Utekelezaji Wako:**
+**Jaribu Utekelezaji Wako:**
-1. Ingia kwenye programu yako ya benki
-2. Fanya upya ukurasa wa kivinjari
-3. Thibitisha unakaa umeingia na uko kwenye dashibodi
+1. Ingia kwenye app yako ya benki
+2. Fanyia upya ukurasa wa kivinjari
+3. Thibitisha bado uko umeingia na uko kwenye dashibodi
4. Funga na fungua tena kivinjari chako
-5. Rudi kwenye programu yako na thibitisha bado uko umeingia
+5. Rudi kwenye app yako na hakikisha bado umeingia
+
+🎉 **Mafanikio Yamepatikana**: Umefanikiwa kutekeleza usimamizi wa hali ya kudumu! App yako sasa hufanya kazi kama programu ya mtandao ya kitaalamu.
-🎉 **Ufanisi Umefikiwa**: Umefanikiwa kutekeleza usimamizi wa hali ya kudumu! Programu yako sasa inafanya kazi kama programu ya kitaalamu ya wavuti.
+### 🎯 Chunguzi la Kifundisho: Mimariko ya Kudumu
-## Kuweka Mizani Kati ya Uhifadhi na Ufreshi wa Data
+**Uelewa wa Mimariko**: Umetekeleza safu ya kudumu ya kisasa inayobadilisha uzoefu wa mtumiaji na urahisi wa usimamizi wa data.
-Mfumo wetu wa uhifadhi unadumisha vikao vya mtumiaji kwa mafanikio, lakini unaleta changamoto mpya: uchakavu wa data. Wakati watumiaji au programu nyingi zinapobadilisha data sawa ya seva, taarifa iliyohifadhiwa ndani inakuwa ya zamani.
+**Mafundisho Muhimu yaliyopatikana**:
+- **Usanifuaji wa JSON**: Kubadilisha vitu tata kuwa nyuzi za kuhifadhi
+- **Mlinganyo Moja kwa Moja**: Mabadiliko ya hali husababisha uhifadhi wa kudumu
+- **Urekebishaji wa Kikao**: Programu zinaweza kurudisha mtazamo wa mtumiaji baada ya kuingiliwa
+- **Kudumu Kwenye Kitu Kimoja**: Kazi moja ya masasisho hushughulikia sehemu zote za uhifadhi
-Hali hii inafanana na mabaharia wa Viking waliotegemea ramani za nyota zilizohifadhiwa na uchunguzi wa nyota wa sasa. Ramani zilitoa uthabiti, lakini mabaharia walihitaji uchunguzi mpya ili kuzingatia hali zinazobadilika. Vivyo hivyo, programu yetu inahitaji hali ya mtumiaji iliyohifadhiwa na data ya sasa ya seva.
+**Muunganisho wa Sekta**: Mfumo huu wa kudumu ni msingi wa Progressive Web Apps (PWAs), programu za offline kwanza, na uzoefu wa mtandao wa kisasa wa simu. Unajenga uwezo wa kiwango cha uzalishaji.
+
+**Swali la Tafakari**: Utabadilishaje mfumo huu kushughulikia akaunti nyingi za mtumiaji kwenye kifaa kimoja? Fikiria mambo ya faragha na usalama.
+
+## Kuweka Mizani kati ya Kudumu na Ufreshi wa Data
+
+Mfumo wetu wa kudumu umetunza vikao vya watumiaji kwa mafanikio, lakini umeleta changamoto mpya: data ya zamani. Wakati watumiaji wengi au programu hubadilisha data sawa ya server, taarifa zilizogandishwa haziwezi kusasishwa.
+
+Hali hii ni kama wavaazi wa Viking walivyotegemea ramani za nyota zilizo hifadhiwa pamoja na maangalia ya nyota wa sasa. Ramani zilihakikisha uthabiti, lakini wapiga ramani walihitaji maangalia mapya ili kuzingatia hali zinabadilika. Vivyo hivyo, programu yetu inahitaji hali ya kudumu ya mtumiaji na data ya sasa ya server.
**🧪 Kugundua Tatizo la Ufreshi wa Data:**
-1. Ingia kwenye dashibodi ukitumia akaunti ya `test`
-2. Endesha amri hii kwenye terminal ili kuiga muamala kutoka chanzo kingine:
+1. Ingia kwenye dashibodi kwa kutumia akaunti ya `test`
+2. Endesha amri hii kwenye terminal kuiga muamala kutoka chanzo kingine:
```sh
curl --request POST \
@@ -403,31 +591,47 @@ curl --request POST \
http://localhost:5000/api/accounts/test/transactions
```
-3. Fanya upya ukurasa wa dashibodi yako kwenye kivinjari
-4. Angalia ikiwa unaona muamala mpya
+3. Fanyia upya ukurasa wako wa dashibodi kwenye kivinjari
+4. Angalia kama unaona muamala mpya
-**Kile ambacho jaribio hili linaonyesha:**
-- **Inaonyesha** jinsi localStorage inaweza kuwa "chakavu" (ya zamani)
-- **Inaiga** hali halisi ambapo mabadiliko ya data hutokea nje ya programu yako
-- **Inafichua** mvutano kati ya uhifadhi na ufreshi wa data
+**Kile jaribio hili linaonyesha:**
+- **Inaonesha** jinsi uhifadhi wa ndani unaweza kuwa "zamani" (hauko sawa)
+- **Inaigiza** hali halisi ambapo data hubadilika nje ya app yako
+- **Inafichua** mgogoro kati ya kudumu na ufreshi wa data
-**Changamoto ya Uchakavu wa Data:**
+**Changamoto ya Data Zamani:**
| Tatizo | Sababu | Athari kwa Mtumiaji |
-|--------|--------|---------------------|
-| **Data Chakavu** | localStorage haimaliziki kiotomatiki | Watumiaji wanaona taarifa za zamani |
-| **Mabadiliko ya Seva** | Programu/Watumiaji wengine hubadilisha data sawa | Maoni yasiyo thabiti kati ya majukwaa |
-| **Akiba vs. Uhalisia** | Akiba ya ndani haifanani na hali ya seva | Uzoefu duni wa mtumiaji na mkanganyiko |
+|---------|-------|-------------|
+| **Data Zamani** | localStorage haijagiika kiotomatiki | Watumiaji wanaona taarifa za zamani |
+| **Mabadiliko ya Server** | Programu/watumiaji wengine hubadilisha data moja | Mtazamo usio sambamba katika majukwaa |
+| **Cache vs. Ukweli** | Cache ya ndani haifanani na hali ya server | Uzoefu mbaya wa mtumiaji na mkanganyiko |
**Mkakati wa Suluhisho:**
-Tutatekeleza muundo wa "ufreshi wakati wa kupakia" ambao unadumisha faida za uhifadhi huku ukihakikisha usahihi wa data.
-
-### Kazi: Tekeleza Mfumo wa Ufreshi wa Data
+Tutatekeleza mfumo wa "kusasisha kwa upakiaji" unaowezesha faida za udumu na uhifadhi wa data safi. Njia hii huhakikisha uzoefu laini wa mtumiaji huku ikihakikisha usahihi wa data.
+
+```mermaid
+sequenceDiagram
+ participant U as Mtumiaji
+ participant A as App
+ participant L as localStorage
+ participant S as Seva
+
+ U->>A: Fungua app
+ A->>L: Pakia hali iliyohifadhiwa
+ L-->>A: Rudisha data iliyohifadhiwa
+ A->>U: Onyesha UI mara moja
+ A->>S: Pata data safi
+ S-->>A: Rudisha data ya sasa
+ A->>L: Sasisha hifadhidata
+ A->>U: Sasisha UI na data safi
+```
+### Kazi: Tekeleza Mfumo wa Kusasisha Data
-Tutatengeneza mfumo ambao unaleta kiotomatiki data mpya kutoka kwa seva huku ukidumisha faida za usimamizi wetu wa hali ya kudumu.
+Tutaunda mfumo unaopakua data safi kutoka server pamoja na kutunza faida za usimamizi wa hali ya kudumu.
-**Hatua ya 1: Tengeneza Kisasa cha Data ya Akaunti**
+**Hatua 1: Tengeneza Kisahihishaji cha Data ya Akaunti**
```js
async function updateAccountData() {
@@ -446,14 +650,14 @@ async function updateAccountData() {
```
**Kuelewa mantiki ya kazi hii:**
-- **Hukagua** ikiwa mtumiaji ameingia (state.account ipo)
-- **Huelekeza** kwenye kujiondoa ikiwa hakuna kikao halali kilichopatikana
-- **Huleta** data mpya ya akaunti kutoka kwa seva kwa kutumia kazi ya `getAccount()` iliyopo
-- **Hushughulikia** makosa ya seva kwa kujiondoa vikao visivyo halali
-- **Husasa** hali na data mpya kwa kutumia mfumo wetu wa kusasisha uliodhibitiwa
-- **Husababisha** uhifadhi wa localStorage kiotomatiki kupitia kazi ya `updateState()`
+- **Hukagua** kama mtumiaji anaingia sasa (state.account ipo)
+- **Hupeleka** mtu aondoke ikiwa hakuna kikao halali
+- **Huleta** data safi ya akaunti kutoka server kwa kutumia kazi `getAccount()`
+- **Hushughulikia** makosa ya server kwa kuondoa vikao visivyo halali
+- **Huisasisha** hali kwa data safi kwa kutumia mfumo wetu wa masasisho
+- **Huisababishia** uhifadhi wa moja kwa moja wa localStorage kupitia `updateState()`
-**Hatua ya 2: Tengeneza Kishughulikia Ufreshi wa Dashibodi**
+**Hatua 2: Tengeneza Kishughulikiaji cha Kusasisha Dashibodi**
```js
async function refresh() {
@@ -462,15 +666,15 @@ async function refresh() {
}
```
-**Kile ambacho kazi hii ya ufreshi inakamilisha:**
-- **Husimamia** mchakato wa ufreshi wa data na masasisho ya UI
-- **Husubiri** data mpya ipakie kabla ya kusasisha onyesho
-- **Hakikisha** dashibodi inaonyesha taarifa za sasa zaidi
-- **Hudumisha** mgawanyo safi kati ya usimamizi wa data na masasisho ya UI
+**Kile kazi hii ya kusasisha inafanya:**
+- **Iratibu** mchakato wa kusasisha data na masasisho ya UI
+- **Inasubiri** data safi ipakuliwe kabla ya kusasisha onyesho
+- **Inahakikisha** dashibodi inaonesha taarifa za hivi sasa zaidi
+- **Inazuia** ufungamano kati ya usimamizi wa data na masasisho ya UI
-**Hatua ya 3: Jumuisha na Mfumo wa Njia**
+**Hatua 3: Unganisha na Mfumo wa Njia**
-Sasisha usanidi wa njia zako ili kusababisha ufreshi kiotomatiki:
+Sasisha usanidi wa njia yako ili kuanzisha kusasisha moja kwa moja:
```js
const routes = {
@@ -479,71 +683,126 @@ const routes = {
};
```
-**Jinsi ujumuishaji huu unavyofanya kazi:**
-- **Hutekeleza** kazi ya ufreshi kila wakati njia ya dashibodi inapopakia
-- **Hakikisha** data mpya inaonyeshwa kila wakati watumiaji wanapohamia kwenye dashibodi
-- **Hudumisha** muundo wa njia uliopo huku ukiongeza ufreshi wa data
-- **Hutoa** muundo thabiti wa uanzishaji maalum wa njia
-
-**Kupima Mfumo Wako wa Ufreshi wa Data:**
-
-1. Ingia kwenye programu yako ya benki
-2. Endesha amri ya curl kutoka awali ili kuunda muamala mpya
-3. Fanya upya ukurasa wa dashibodi yako au nenda mbali na urudi
-4. Thibitisha kuwa muamala mpya unaonekana mara moja
+**Jinsi muunganisho huu unavyofanya kazi:**
+- **Hutekeleza** kazi ya kusasisha kila mara njia ya dashibodi inapopakuliwa
+- **Hakikisha** data safi daima inaonyeshwa watumiaji wanapotembelea dashibodi
+- **Inatunza** muundo wa njia uliopo huku ikiongeza ufreshi wa data
+- **Inatoa** mfano thabiti wa kuanzisha sehemu maalum za njia
+
+**Jaribu Mfumo wako wa Kusasisha Data:**
+
+1. Ingia kwenye app yako ya benki
+2. Endesha amri ya curl tuliyotumia awali kuunda muamala mpya
+3. Fanyia upya ukurasa wa dashibodi au tembelea mbali na rudi
+4. Thibitisha muamala mpya unaonekana mara moja
+
+🎉 **Mizani Bora Imepatikana**: App yako sasa inachanganya uzoefu laini wa hali ya kudumu pamoja na usahihi wa data safi ya server!
+
+## 📈 Ratiba Yako ya Ujuzi wa Usimamizi wa Hali
+
+```mermaid
+timeline
+ title Safari ya Usimamizi wa Hali ya Kitaalamu
+
+ section Kutambua Tatizo
+ State Issues Diagnosis
+ : Tambua matatizo ya kupoteza kikao
+ : Elewa matatizo ya masasisho yaliyosambazwa
+ : Tambua mahitaji ya usanifu
+
+ section Msingi wa Usanifu
+ Centralized State Design
+ : Tengeneza vitu vya hali vilivyoundwa pamoja
+ : Tekeleza mifumo ya masasisho yenye udhibiti
+ : Anzisha kanuni zisizobadilika
+
+ Predictable Updates
+ : Jifunze matumizi ya Object.freeze()
+ : Jenga mifumo inayorahisisha utambuzi wa makosa
+ : Tengeneza mifano inayoweza kupanuka
+
+ section Ustadi wa Kuhifadhi
+ localStorage Integration
+ : Shughulikia usindikaji wa JSON
+ : Tekeleza usawazishaji wa moja kwa moja
+ : Tengeneza uendelevu wa kikao
+
+ Data Freshness Balance
+ : Shughulikia changamoto za upungufu wa data
+ : Jenga mifumo ya kuhuisha data
+ : Boresha utendakazi dhidi ya usahihi
+
+ section Mifumo ya Kitaalamu
+ Production-Ready Systems
+ : Tekeleza usimamizi wa makosa
+ : Tengeneza usanifu unaoweza kudumishwa
+ : Fuata mbinu bora za sekta
+
+ Advanced Capabilities
+ : Kuwa tayari kwa ujumuishwaji wa mfumo
+ : Kuwa tayari kwa mahitaji magumu ya hali
+ : Msingi wa vipengele vya wakati halisi
+```
+**🎓 Hatua ya Kuandikishwa**: Umefanikiwa kujenga mfumo kamili wa usimamizi wa hali kwa kutumia kanuni zinazotumika katika Redux, Vuex, na maktaba zingine za hali wa kitaalamu. Mifumo hii hukua kutoka programu rahisi hadi programu za viwanda.
-🎉 **Mizani Kamili Imepatikana**: Programu yako sasa inachanganya uzoefu laini wa hali ya kudumu na usahihi wa data mpya ya seva!
+**🔄 Uwezo wa Ngazi Inayofuata**:
+- Tayari kwa ujuzi wa mifumo ya usimamizi wa hali (Redux, Zustand, Pinia)
+- Tayari kutekeleza vipengele vya wakati halisi kwa kutumia WebSockets
+- Umejifunza kujenga Progressive Web Apps zinazoanza offline kwanza
+- Msingi umewekwa kwa mifumo ya hali ya juu kama mashine za hali na wachunguzi
-## Changamoto ya Wakala wa GitHub Copilot 🚀
+## Changamoto ya GitHub Copilot Agent 🚀
-Tumia hali ya Wakala kukamilisha changamoto ifuatayo:
+Tumia hali ya Agent kukamilisha changamoto ifuatayo:
-**Maelezo:** Tekeleza mfumo wa kina wa usimamizi wa hali na utendakazi wa kurudisha/kufanya upya kwa programu ya benki. Changamoto hii itakusaidia kufanya mazoezi ya dhana za hali ya juu za usimamizi wa hali ikiwa ni pamoja na ufuatiliaji wa historia ya hali, masasisho yasiyobadilika, na usawazishaji wa kiolesura cha mtumiaji.
+**Maelezo:** Tekeleza mfumo kamili wa usimamizi wa hali unaojumuisha uwezo wa kufuta/kurudi nyuma kwa mabadiliko kwa app ya benki. Changamoto hii itakuwezesha kufanya mazoezi ya dhana za hali za juu za usimamizi wakiwemo rekodi ya historia ya hali, masasisho yasiyobadilika, na ulinganifu wa kiolesura cha mtumiaji.
-**Kichocheo:** Tengeneza mfumo wa hali ulioboreshwa unaojumuisha: 1) Kundi la historia ya hali linalofuatilia hali zote za awali, 2) Kazi za kurudisha na kufanya upya zinazoweza kurudi kwenye hali za awali, 3) Vitufe vya UI vya operesheni za kurudisha/kufanya upya kwenye dashibodi, 4) Kikomo cha historia cha hali 10 ili kuzuia masuala ya kumbukumbu, na 5) Usafishaji sahihi wa historia wakati mtumiaji anajiondoa. Hakikisha utendakazi wa kurudisha/kufanya upya unafanya kazi na mabadiliko ya salio la akaunti na unadumu kati ya upya wa kivinjari.
+**Onyesho:** Tengeneza mfumo ulioimarishwa wa usimamizi wa hali unaojumuisha: 1) safu ya historia ya hali inayofuatilia hali zote zilizopita, 2) kazi za kufuta na kutekeleza tena zinazoweza kurudisha hali zilizopita, 3) vifungo vya UI kwa operesheni za ufuta/tekeleza tena kwenye dashibodi, 4) kikomo cha historia cha hali 10 ili kuzuia matatizo ya kumbukumbu, na 5) usafishaji wa historia baada ya mtumiaji kuondoka. Hakikisha utendaji wa ufuta/tekeleza tena unafanya kazi na mabadiliko ya salio la akaunti na unadumu hata baada ya kivinjari kufanywa upya.
-Jifunze zaidi kuhusu [hali ya wakala](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode) hapa.
+Jifunze zaidi kuhusu [agent mode](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode) hapa.
## 🚀 Changamoto: Uboreshaji wa Uhifadhi
-Utekelezaji wako sasa unashughulikia vikao vya mtumiaji, ufreshi wa data, na usimamizi wa hali kwa ufanisi. Hata hivyo, fikiria ikiwa mbinu yetu ya sasa inasawazisha kwa ufanisi uhifadhi na utendakazi.
+Utekelezaji wako sasa unashughulikia vikao vya watumiaji, kusasisha data, na usimamizi wa hali kwa ufanisi. Hata hivyo, fikiria kama njia yetu ya sasa inalinganisha vyema ufanisi wa uhifadhi na kazi.
-Kama mabingwa wa chess wanaotofautisha kati ya vipande muhimu na vigae vinavyoweza kutolewa, usimamizi mzuri wa hali unahitaji kutambua data gani lazima ihifadhiwe dhidi ya data gani inapaswa kuwa mpya kila wakati kutoka kwa seva.
+Kama mabingwa wa chess wanaotofautisha kati ya vipande muhimu na askari wa kurudisha mithili, usimamizi mzuri wa hali unahitaji kubaini ni data gani lazima idumu na ni ipi inapaswa kila wakati kuwa mpya kutoka server.
**Uchambuzi wa Uboreshaji:**
-Tathmini utekelezaji wako wa localStorage wa sasa na fikiria maswali haya ya kimkakati:
-- Ni taarifa gani ya chini inayohitajika kudumisha uthibitisho wa mtumiaji?
-- Ni data gani hubadilika mara kwa mara kiasi kwamba uhifadhi wa ndani hauna faida?
-- Uboreshaji wa uhifadhi unaweza kuboresha utendakazi bila kupunguza uzoefu wa mtumiaji?
+Tathmini utekelezaji wako wa localStorage sasa na fikiria maswali haya ya kimkakati:
+- Ni taarifa ngapi minimal zinazohitajika kudumisha uthibitishaji wa mtumiaji?
+- Ni data gani hubadilika mara kwa mara kiasi ambayo kuhifadhiwa mara nyingi ndani haileti faida?
+- Je, uboreshaji wa uhifadhi unaweza kuboresha utendaji bila kupunguza uzoefu wa mtumiaji?
-Aina hii ya uchambuzi wa usanifu inawatofautisha watengenezaji wenye uzoefu wanaozingatia utendakazi na ufanisi katika suluhisho zao.
+Aina hii ya uchambuzi wa miundo hutoa tofauti kwa watengenezaji wenye uzoefu wanaofikiria kazi na ufanisi kwa suluhisho zao.
**Mkakati wa Utekelezaji:**
-- **Tambua** data muhimu ambayo lazima ihifadhiwe (labda tu kitambulisho cha mtumiaji)
-- **Badilisha** utekelezaji wako wa localStorage ili kuhifadhi tu data muhimu ya kikao
-- **Hakikisha** data mpya inapakiwa kila wakati kutoka kwa seva wakati wa ziara za dashibodi
-- **Jaribu** kwamba mbinu yako iliyoboreshwa inadumisha uzoefu sawa wa mtumiaji
+- **Baini** data muhimu kabisa inayohitaji kudumu (labda ni kitambulisho cha mtumiaji tu)
+- **Badilisha** utekelezaji wako wa localStorage kuhifadhi tu data muhimu ya kikao
+- **Hakikisha** data safi kila wakati inapakia kutoka server unapotembelea dashibodi
+- **Jaribu** kuwa njia yako iliyoboreshwa bado inatunza uzoefu mmoja wa mtumiaji
-**Fikra ya Juu:**
-- **Linganisheni** faida na hasara kati ya kuhifadhi data kamili ya akaunti dhidi ya tokeni za uthibitisho pekee
-- **Andika** maamuzi yako na mantiki kwa wanachama wa timu ya baadaye
+**Kuzingatia kwa Juu:**
+- **Linganisho** la manufaa na hasara kati ya kuhifadhi data kamili ya akaunti dhidi ya vitambulisho vya uthibitishaji pekee
+- **Andika** maamuzi yako na sababu zako kwa wanateam wa baadaye
-Changamoto hii itakusaidia kufikiria kama mtengenezaji wa kitaalamu anayezingatia uzoefu wa mtumiaji na ufanisi wa programu. Chukua muda wako kujaribu mbinu tofauti!
+Changamoto hii itakusaidia kufikiri kama mtaalamu anayeangalia uzoefu wa mtumiaji na ufanisi wa programu. Chukua muda wako kujaribu mbinu mbalimbali!
-## Jaribio la Baada ya Somo
+## Mtihani wa Baada ya Mhadhara
-[Jaribio la baada ya somo](https://ff-quizzes.netlify.app/web/quiz/48)
+[Post-lecture quiz](https://ff-quizzes.netlify.app/web/quiz/48)
-## Kazi
+## Kazi ya Nyumbani
-[Tekeleza "Ongeza muamala" dirisha](assignment.md)
+[Implement "Add transaction" dialog](assignment.md)
-Hapa kuna mfano wa matokeo baada ya kukamilisha kazi:
+Huu ni mfano wa matokeo baada ya kukamilisha kazi:
-
+
---
-**Kanusho**:
-Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kwa usahihi, tafadhali fahamu kuwa tafsiri za kiotomatiki zinaweza kuwa na makosa au kutokuwa sahihi. Hati ya asili katika lugha yake ya awali inapaswa kuzingatiwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya kitaalamu ya binadamu inapendekezwa. Hatutawajibika kwa kutoelewana au tafsiri zisizo sahihi zinazotokana na matumizi ya tafsiri hii.
\ No newline at end of file
+
+**Hapati**:
+Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Wakati tunajitahidi kwa usahihi, tafadhali fahamu kwamba tafsiri zilizotengenezwa kwa mashine zinaweza kuwa na makosa au upungufu wa usahihi. Hati ya asili katika lugha yake ya asili inapaswa kuzingatiwa kama chanzo cha mamlaka. Kwa taarifa za muhimu sana, tafsiri ya kitaalamu inayotolewa na watu inashauriwa. Hatubeba uwajibikaji wowote kwa kutoelewana au tafsiri potofu zinazotokana na matumizi ya tafsiri hii.
+
\ No newline at end of file
diff --git a/translations/sw/7-bank-project/4-state-management/assignment.md b/translations/sw/7-bank-project/4-state-management/assignment.md
index 916b1abe9..0f481d87e 100644
--- a/translations/sw/7-bank-project/4-state-management/assignment.md
+++ b/translations/sw/7-bank-project/4-state-management/assignment.md
@@ -112,7 +112,7 @@ Rejelea [nyaraka za API ya seva](../api/README.md) kwa:
**Matokeo Yanayotarajiwa:**
Baada ya kukamilisha kazi hii, programu yako ya benki inapaswa kuwa na kipengele kamili cha "Ongeza Muamala" ambacho kinaonekana na kinafanya kazi kitaalamu:
-
+
## Kupima Utekelezaji Wako
diff --git a/translations/sw/7-bank-project/README.md b/translations/sw/7-bank-project/README.md
index cbc0c145f..a6e4c04a8 100644
--- a/translations/sw/7-bank-project/README.md
+++ b/translations/sw/7-bank-project/README.md
@@ -11,7 +11,7 @@ CO_OP_TRANSLATOR_METADATA:
Katika mradi huu, utajifunza jinsi ya kujenga benki ya kufikirika. Masomo haya yanajumuisha maelekezo ya jinsi ya kupanga programu ya wavuti na kutoa njia, kujenga fomu, kusimamia hali (state), na kupata data kutoka kwa API ambayo unaweza kutumia kupata data ya benki.
-|  |  |
+|  |  |
|--------------------------------|--------------------------------|
## Masomo
diff --git a/translations/sw/8-code-editor/1-using-a-code-editor/README.md b/translations/sw/8-code-editor/1-using-a-code-editor/README.md
index d8ee82abc..be20e5862 100644
--- a/translations/sw/8-code-editor/1-using-a-code-editor/README.md
+++ b/translations/sw/8-code-editor/1-using-a-code-editor/README.md
@@ -1,372 +1,639 @@
-# Kutumia Mhariri wa Nambari: Kumiliki VSCode.dev
+# Kutumia Mhariri wa Msimbo: Kuweza VSCode.dev
-Unakumbuka kwenye *The Matrix* wakati Neo alihitaji kuunganishwa na kompyuta kubwa ili kuingia kwenye ulimwengu wa kidijitali? Zana za maendeleo ya mtandao za leo ni kinyume kabisa – uwezo wa ajabu unaopatikana kutoka popote. VSCode.dev ni mhariri wa nambari unaotegemea kivinjari ambao huleta zana za maendeleo ya kitaalamu kwenye kifaa chochote chenye muunganisho wa intaneti.
+Kumbuka katika *The Matrix* pale Neo alipotakiwa kuunganisha kwenye kituo kikubwa cha kompyuta ili kufikia dunia ya kidijitali? Vifaa vya maendeleo ya wavuti vya leo ni hadithi kinyume – uwezo mkubwa sana unaopatikana kutoka mahali popote. VSCode.dev ni mhariri wa msimbo unaotumia kivinjari ambao huleta vifaa vya maendeleo ya kitaalamu kwa kifaa chochote kilicho na muunganisho wa intaneti.
-Kama vile mashine ya uchapishaji ilivyofanya vitabu kupatikana kwa kila mtu, si kwa waandishi tu katika monasteri, VSCode.dev inafanya coding kuwa ya kila mtu. Unaweza kufanya kazi kwenye miradi kutoka kwenye kompyuta ya maktaba, maabara ya shule, au popote unapoingia kwenye kivinjari. Hakuna usakinishaji, hakuna vikwazo vya "Nahitaji mpangilio wangu maalum".
+Kama vile mashine ya kuchapisha ilivyofanya vitabu kupatikana kwa kila mtu, siwaandishi tu katika monastari, VSCode.dev huleta usawa wa upatikanaji wa kuandika msimbo. Unaweza kufanya kazi kwenye miradi kutoka kwenye kompyuta ya maktaba, maabara ya shule, au mahali popote ambapo unapata kivinjari. Hakuna usakinishaji, hakuna vizingiti vya "nahitaji usanidi wangu maalum".
-Mwisho wa somo hili, utaelewa jinsi ya kuzunguka VSCode.dev, kufungua hifadhi za GitHub moja kwa moja kwenye kivinjari chako, na kutumia Git kwa udhibiti wa toleo – ujuzi ambao watengenezaji wa kitaalamu hutegemea kila siku.
+Mwisho wa somo hili, utakuwa umeelewa jinsi ya kuvinjari VSCode.dev, kufungua hifadhidata za GitHub moja kwa moja kwenye kivinjari chako, na kutumia Git kwa ajili ya udhibiti wa matoleo – ujuzi wote ambao wataalamu wa maendeleo hutumia kila siku.
-## Utakachojifunza
+## ⚡ Unachoweza Kufanya kwa Dakika 5 Zijazo
-Baada ya kupitia somo hili pamoja, utaweza:
+**Njia ya Kuanza Haraka kwa Waendelezaji Wenye Muda Mfupi**
-- Kuzunguka VSCode.dev kama ni nyumbani kwako – ukipata kila unachohitaji bila kupotea
-- Kufungua hifadhi yoyote ya GitHub kwenye kivinjari chako na kuanza kuhariri mara moja (hii ni ya kichawi sana!)
-- Kutumia Git kufuatilia mabadiliko yako na kuhifadhi maendeleo yako kama mtaalamu
-- Kuongeza nguvu kwa mhariri wako kwa viendelezi vinavyofanya coding kuwa haraka na ya kufurahisha
-- Kuunda na kupanga faili za miradi kwa kujiamini
+```mermaid
+flowchart LR
+ A[⚡ Dakika 5] --> B[Tembelea vscode.dev]
+ B --> C[Unganisha akaunti ya GitHub]
+ C --> D[Fungua hifadhi yoyote]
+ D --> E[Anza kuhariri mara moja]
+```
+- **Dakika 1**: Nenda kwenye [vscode.dev](https://vscode.dev) - hakuna usakinishaji unaohitajika
+- **Dakika 2**: Ingia kwa kutumia GitHub kuungana na hifadhidata zako
+- **Dakika 3**: Jaribu mbinu ya URL: badilisha `github.com` kuwa `vscode.dev/github` katika URL yoyote ya hifadhidata
+- **Dakika 4**: Tengeneza faili jipya na uangalie jinsi mwangaza wa sintaksia unavyofanya kazi moja kwa moja
+- **Dakika 5**: Fanya mabadiliko na yafanye kuwasilishwa kupitia paneli ya Udhibiti wa Chanzo
+
+**URL ya Jaribio la Haraka**:
+```
+# Transform this:
+github.com/microsoft/Web-Dev-For-Beginners
+
+# Into this:
+vscode.dev/github/microsoft/Web-Dev-For-Beginners
+```
+
+**Kwa Nini Hii ni Muhimu**: Kwa dakika 5 tu, utapata uhuru wa kuandika msimbo mahali popote ukiwa na vifaa vya kitaalamu. Hii ni mustakabali wa maendeleo - inapatikana, yenye nguvu, na ya mara moja.
+
+## 🗺️ Safari Yako ya Kujifunza Kupitia Maendeleo ya Wingu
+
+```mermaid
+journey
+ title Kutoka Usanidi wa Mitaa hadi Utaalamu wa Maendeleo ya Wingu
+ section Kuelewa Jukwaa
+ Gundua uhariri wa mtandao: 4: You
+ Unganisha na mfumo wa GitHub: 6: You
+ Shuhudia urambazaji wa kiolesura: 7: You
+ section Ujuzi wa Usimamizi wa Faili
+ Tengeneza na panga faili: 5: You
+ Hariri kwa muonekano wa sintaksia: 7: You
+ Pita kwenye miundo ya mradi: 8: You
+ section Utaalamu wa Udhibiti wa Toleo
+ Elewa ujumuishaji wa Git: 6: You
+ Fanya mazoezi ya mchakato wa commit: 8: You
+ Shuhudia mifumo ya ushirikiano: 9: You
+ section Ubunifu wa Kitaalamu
+ Sakinisha nyongeza zenye nguvu: 7: You
+ Panga mazingira ya maendeleo: 8: You
+ Tengeneza michakato binafsi: 9: You
+```
+**Lengo la Safari Yako**: Mwisho wa somo hili, utakuwa umeweza kutumia mazingira ya kitaalamu ya maendeleo ya wingu yanayofanya kazi kutoka kifaa chochote, kukuwezesha kuandika msimbo kwa kutumia vifaa vinavyotumiwa na waendelezaji katika makampuni makubwa ya teknolojia.
+
+## Unachojifunza
-## Utakachohitaji
+Baada ya kutembea pamoja, utaweza:
+
+- Kuvinjari VSCode.dev kama ni nyumba yako ya pili – kupata kila unachohitaji bila kupotea
+- Kufungua hifadhidata yoyote ya GitHub kwenye kivinjari chako na kuanza kuhariri mara moja (hii ni ya kushangaza sana!)
+- Kutumia Git kufuatilia mabadiliko yako na kuhifadhi maendeleo kama mtaalamu
+- Kuongeza nguvu kwa mhariri wako kwa kutumia nyongeza zinazofanya kuandika msimbo kuwa haraka na kufurahisha zaidi
+- Kuunda na kupanga faili za mradi kwa kujiamini
+
+## Utabidi Unachohitaji
Mahitaji ni rahisi:
-- Akaunti ya bure ya [GitHub](https://github.com) (tutakuelekeza jinsi ya kuunda ikiwa unahitaji)
-- Uelewa wa msingi wa vivinjari vya wavuti
-- Somo la Misingi ya GitHub linatoa msingi mzuri, ingawa si lazima
+- Akaunti ya bure ya [GitHub](https://github.com) (tutakuongoza kuunda kama inahitajika)
+- Uwezo wa msingi wa kutumia vivinjari vya wavuti
+- Somo la Misingi ya GitHub linatoa msingi mzuri wa maarifa, ingawa si sharti
+
+> 💡 **Mpya kwa GitHub?** Kuunda akaunti ni bure na huchukua dakika chache. Kama vile kadi ya maktaba inavyokuwezesha kupata vitabu duniani kote, akaunti ya GitHub hukufungulia milango ya hifadhidata za msimbo mtandao mzima.
-> 💡 **Mgeni wa GitHub?** Kuunda akaunti ni bure na huchukua dakika chache. Kama vile kadi ya maktaba inavyokupa ufikiaji wa vitabu duniani kote, akaunti ya GitHub inafungua milango kwa hifadhi za nambari kote mtandaoni.
+## 🧠 Muhtasari wa Mfumo wa Maendeleo ya Wingu
+
+```mermaid
+mindmap
+ root((VSCode.dev Utaalamu))
+ Platform Benefits
+ Accessibility
+ Uhuru wa Kifaa
+ Hakuna Ufungaji Unahitajika
+ Sasisho la Mara Moja
+ Ufikiaji Ulimwenguni
+ Integration
+ Muunganisho wa GitHub
+ Mfumo wa Kukimbia Hifadhi
+ Uhifadhi wa Mipangilio
+ Tayari kwa Ushirikiano
+ Development Workflow
+ File Management
+ Muundo wa Mradi
+ Mwangaza wa Sarufi
+ Kuhariri Tab Tofauti
+ Sifa za Hifadhi Yaotomatiki
+ Version Control
+ Muunganisho wa Git
+ Mizunguko ya Kuajiri
+ Usimamizi wa Matawi
+ Ufuatiliaji wa Mabadiliko
+ Customization Power
+ Extensions Ecosystem
+ Vifaa vya Uzalishaji
+ Msaada wa Lugha
+ Chaguo za Mandhari
+ Njia Fupi za Custom
+ Environment Setup
+ Mapendeleo Binafsi
+ Mpangilio wa Eneo la Kazi
+ Muunganisho wa Vifaa
+ Uboreshaji wa Mtiririko wa Kazi
+ Professional Skills
+ Industry Standards
+ Udhibiti wa Toleo
+ Ubora wa Msimbo
+ Ushirikiano
+ Nyaraka
+ Career Readiness
+ Kazi Mbali
+ Maendeleo ya Wingu
+ Miradi ya Timu
+ Chanzo Huru
+```
+**Kanuni Muhimu**: Mazingira ya maendeleo ya msingi wa wingu ni mustakabali wa kuandika msimbo – yanatoa zana za kitaalamu zinazopatikana kwa urahisi, zinazoshirikiana, na zisizo tegemea jukwaa lolote.
-## Kwa Nini Wahitaji Mhariri wa Nambari wa Kivinjari?
+## Kwa Nini Wahariri wa Msimbo wa Mtandao ni Muhimu
-Kabla ya intaneti, wanasayansi katika vyuo vikuu tofauti hawakuweza kushiriki utafiti kwa urahisi. Kisha ARPANET ikaja miaka ya 1960, ikunganisha kompyuta kwa umbali. Wahariri wa nambari wa kivinjari hufuata kanuni hiyo hiyo – kufanya zana zenye nguvu kupatikana bila kujali eneo lako au kifaa.
+Kabla ya intaneti, wanasayansi katika vyuo mbalimbali hawakuweza kushirikiana tafiti kwa urahisi. Kisha ARPANET ilikuja miaka ya 1960, ikawaunganisha kompyuta kutoka maeneo tofauti. Wahariri wa msimbo wa mtandao hufuata kanuni hii ile ile – kufanya zana za nguvu zipatikane bila kujali mahali ulipo au kifaa unachotumia.
-Mhariri wa nambari hufanya kazi kama eneo lako la maendeleo, ambapo unaandika, kuhariri, na kupanga faili za nambari. Tofauti na wahariri wa maandishi rahisi, wahariri wa nambari wa kitaalamu hutoa mwangaza wa sintaksia, kugundua makosa, na vipengele vya usimamizi wa miradi.
+Mhariri wa msimbo hutumika kama eneo lako la kazi la maendeleo, ambapo unaandika, kuhariri, na kupanga faili za msimbo. Tofauti na wahariri wa maandishi rahisi, wahariri wa msimbo wa kitaalamu hutoa mwangaza wa sintaksia, utambuzi wa makosa, na vipengele vya usimamizi wa miradi.
VSCode.dev huleta uwezo huu kwenye kivinjari chako:
-**Faida za kuhariri kwa kivinjari:**
+**Faida za kuhariri mtandaoni:**
-| Kipengele | Maelezo | Faida ya Kivitendo |
-|-----------|---------|--------------------|
-| **Uhuru wa Jukwaa** | Inaendeshwa kwenye kifaa chochote chenye kivinjari | Fanya kazi kutoka kompyuta tofauti bila shida |
-| **Hakuna Usakinishaji Unaohitajika** | Ufikiaji kupitia URL ya wavuti | Epuka vikwazo vya usakinishaji wa programu |
-| **Sasisho za Kiotomatiki** | Daima ina toleo la hivi karibuni | Pata vipengele vipya bila sasisho za mikono |
-| **Muunganisho wa Hifadhi** | Muunganisho wa moja kwa moja na GitHub | Hariri nambari bila usimamizi wa faili za ndani |
+| Kipengele | Maelezo | Faida Zaidi |
+|---------|-------------|----------|
+| **Hutoa Uhuru wa Jukwaa Lolote** | Inaendeshwa kwenye kifaa chochote chenye kivinjari | Fanya kazi kutoka kompyuta tofauti bila shida |
+| **Hakuna Usakinishaji Unahitajika** | Inapatikana kupitia URL ya wavuti | Epuka vizuizi vya usakinishaji wa programu |
+| **Mabadiliko Ya Moja kwa Moja** | Huuendeshwa kwa toleo la hivi karibuni kila mara | Upatikanaji wa sifa mpya bila usasishaji wa mkono |
+| **Muunganisho wa Hifadhidata** | Muunganisho wa moja kwa moja na GitHub | Hariri msimbo bila kusimamia faili za ndani |
-**Matokeo ya kivitendo:**
-- Mwendelezo wa kazi katika mazingira tofauti
-- Kiolesura thabiti bila kujali mfumo wa uendeshaji
+**Athari za vitendo:**
+- Kuendelea kwa kazi katika mazingira tofauti
+- Muonekano thabiti bila kujali mfumo wa uendeshaji
- Uwezo wa kushirikiana mara moja
-- Mahitaji ya uhifadhi wa ndani yaliyopunguzwa
+- Kupunguza hitaji la kuhifadhi kwa kifaa cha eneo la nahe
## Kuchunguza VSCode.dev
-Kama vile maabara ya Marie Curie ilivyokuwa na vifaa vya kisasa katika nafasi rahisi, VSCode.dev ina zana za maendeleo ya kitaalamu ndani ya kiolesura cha kivinjari. Programu hii ya wavuti hutoa utendaji wa msingi sawa na wahariri wa nambari wa desktop.
+Kama vile maabara ya Marie Curie ilivyokuwa na vifaa vya hali ya juu katika nafasi rahisi, VSCode.dev hujumuisha zana za kitaalamu za maendeleo katika jukwaa la kivinjari. Programu hii ya wavuti hutoa uwezo sawa kama wahariri wa msimbo wa kompyuta za mezani.
-Anza kwa kwenda [vscode.dev](https://vscode.dev) kwenye kivinjari chako. Kiolesura kinapakia bila kupakua au kusakinisha mfumo – matumizi ya moja kwa moja ya kanuni za kompyuta ya wingu.
+Anza kwa kuvinjari [vscode.dev](https://vscode.dev) kwenye kivinjari chako. Muonekano huo hujazwa bila kupakua au kusakinisha mfumo wowote – ni utekelezaji wa moja kwa moja wa kanuni za kompyuta za wingu.
### Kuunganisha Akaunti Yako ya GitHub
-Kama vile simu ya Alexander Graham Bell ilivyounganisha maeneo ya mbali, kuunganisha akaunti yako ya GitHub huunganisha VSCode.dev na hifadhi zako za nambari. Unapoulizwa kuingia na GitHub, kukubali muunganisho huu kunapendekezwa.
+Kama vile simu ya Alexander Graham Bell ilivyowezesha mawasiliano ya mbali, kuunganisha akaunti yako ya GitHub huunganisha VSCode.dev na hifadhidata zako. Ukiwaombwa kuingia kwa GitHub, kukubali muunganisho huu kinapendekezwa.
**Muunganisho wa GitHub hutoa:**
-- Ufikiaji wa moja kwa moja wa hifadhi zako ndani ya mhariri
-- Mipangilio na viendelezi vilivyolinganishwa kwenye vifaa tofauti
-- Mtiririko wa kuhifadhi ulio rahisi kwa GitHub
+- Upatikanaji wa moja kwa moja wa hifadhidata zako ndani ya mhariri
+- Mipangilio na nyongeza zimeunganishwa kwenye vifaa mbalimbali
+- Mtiririko rahisi wa kuhifadhi kazi kwenye GitHub
- Mazingira ya maendeleo yaliyobinafsishwa
-### Kujifunza Eneo Lako Jipya la Kazi
+### Kufahamu Eneo Lako Jipya la Kazi
-Mara kila kitu kinapopakia, utaona eneo la kazi safi na lenye mpangilio mzuri ambalo limeundwa kukufanya uzingatie kile kinachojalisha – nambari yako!
+Mara kila kitu kinapopakuliwa, utaona eneo la kazi safi na la kuvutia lililoundwa kukuweka makini na kinachohitajika – msimbo wako!
-
+
-**Hapa kuna ziara ya eneo:**
-- **Upau wa Shughuli** (kile kipande upande wa kushoto): Urambazaji wako kuu na Explorer 📁, Tafuta 🔍, Udhibiti wa Chanzo 🌿, Viendelezi 🧩, na Mipangilio ⚙️
-- **Upau wa Pembeni** (paneli karibu nayo): Hubadilika kuonyesha maelezo yanayofaa kulingana na kile ulichoteua
-- **Eneo la Mhariri** (nafasi kubwa katikati): Hapa ndipo uchawi hutokea – eneo lako kuu la kuandika nambari
+**Hapa ni ziara yako ya mtaa:**
+- **Ukuta wa Shughuli** (ukingo wa kushoto): Urambazaji wako mkuu una Explorer 📁, Tafuta 🔍, Udhibiti wa Chanzo 🌿, Nyongeza 🧩, na Mipangilio ⚙️
+- **Upau wa Pembeni** (bamba upande wake): Hubadilika kuonyesha taarifa husika kulingana na unachochagua
+- **Eneo la Mhariri** (sehemu kubwa katikati): Hapa ndipo uchawi unapotokea – eneo lako kuu la kuandika msimbo
-**Chukua muda kuchunguza:**
-- Bonyeza ikoni za Upau wa Shughuli na uone kila moja inafanya nini
-- Angalia jinsi upau wa pembeni unavyosasisha kuonyesha maelezo tofauti – ni nzuri, sivyo?
-- Mwonekano wa Explorer (📁) pengine ndio utatumia muda mwingi, kwa hivyo zoea nao
+**Chukua muda kugundua:**
+- Bonyeza alama za Ukuta wa Shughuli na uone kila moja inavyofanya kazi gani
+- Angalia jinsi upau wa pembeni unavyosasishwa kuonyesha taarifa tofauti – ni nzuri, sivyo?
+- Muonekano wa Explorer (📁) ni sehemu ambayo utatumia zaidi muda wako, hivyo jiandae nayo
-## Kufungua Hifadhi za GitHub
+```mermaid
+flowchart TB
+ subgraph "Usanifu wa Kiolesura cha VSCode.dev"
+ A[Ukanda wa Shughuli] --> B[Mchunguzi 📁]
+ A --> C[Utafutaji 🔍]
+ A --> D[Udhibiti wa Chanzo 🌿]
+ A --> E[Virutubisho 🧩]
+ A --> F[Mipangilio ⚙️]
+
+ B --> G[Mti wa Faili]
+ C --> H[Tafuta & Badilisha]
+ D --> I[Hali ya Git]
+ E --> J[Soko la Virutubisho]
+ F --> K[Mipangilio]
+
+ L[Upau wa Pembeni] --> M[Bodi ya Muktadha]
+ N[Eneo la Mhariri] --> O[Faili za Msimbo]
+ P[Terminala/Matokeo] --> Q[Mstari wa Amri]
+ end
+```
+## Kufungua Hifadhidata za GitHub
-Kabla ya intaneti, watafiti walihitaji kusafiri kimwili kwenda maktaba kupata nyaraka. Hifadhi za GitHub hufanya kazi kwa njia sawa – ni mkusanyiko wa nambari uliowekwa mbali. VSCode.dev huondoa hatua ya jadi ya kupakua hifadhi kwenye mashine yako ya ndani kabla ya kuhariri.
+Kabla ya intaneti, watafiti walilazimika kusafiri kwenda maktaba kupata nyaraka. Hifadhidata za GitHub zinafanya kazi kwa njia ile ile – ni makusanyo ya msimbo yaliyohifadhiwa mbali. VSCode.dev huondoa hatua ya kawaida ya kupakua hifadhidata kwenye mashine yako kabla ya kuhariri.
-Uwezo huu unaruhusu ufikiaji wa haraka wa hifadhi yoyote ya umma kwa kutazama, kuhariri, au kuchangia. Hapa kuna njia mbili za kufungua hifadhi:
+Uwezo huu unaruhusu upatikanaji wa mara moja wa hifadhidata yoyote ya umma kwa ajili ya kutazama, kuhariri, au kuchangia. Hapa kuna njia mbili za kufungua hifadhidata:
-### Njia ya 1: Njia ya Kubonyeza na Kuchagua
+### Njia ya 1: Kidhibiti-na-Klika
-Hii ni bora unapokuwa unaanza upya kwenye VSCode.dev na unataka kufungua hifadhi maalum. Ni rahisi na rafiki kwa wanaoanza:
+Hii ni bora unapoanza mpya kwenye VSCode.dev na unataka kufungua hifadhidata maalum. Ni rahisi na rafiki kwa wanaoanza:
**Hivi ndivyo unavyofanya:**
-1. Nenda kwenye [vscode.dev](https://vscode.dev) ikiwa bado hujafika
-2. Tafuta kitufe cha "Fungua Hifadhi ya Mbali" kwenye skrini ya kukaribisha na bonyeza
+1. Nenda kwenye [vscode.dev](https://vscode.dev) kama bado hujafika
+2. Tafuta kitufe cha "Open Remote Repository" kwenye skrini ya kuanza na kubofya
- 
+ 
-3. Bandika URL yoyote ya hifadhi ya GitHub (jaribu hii: `https://github.com/microsoft/Web-Dev-For-Beginners`)
-4. Bonyeza Enter na uone uchawi ukitokea!
+3. Bandika URL yoyote ya hifadhidata ya GitHub (jaribu hii: `https://github.com/microsoft/Web-Dev-For-Beginners`)
+4. Bonyeza Enter na angalia uchawi unavyotokea!
-**Kidokezo cha kitaalamu - Njia ya Command Palette:**
+**Ushauri wa mtaalamu - Mkato wa Komandi ya Palette:**
-Unataka kujisikia kama mchawi wa coding? Jaribu njia ya mkato ya kibodi: Ctrl+Shift+P (au Cmd+Shift+P kwenye Mac) kufungua Command Palette:
+Unataka kujisikia kama mchawi wa kuandika msimbo? Jaribu mkato huu wa kibodi: Ctrl+Shift+P (au Cmd+Shift+P kwa Mac) kufungua Komandi ya Palette:
-
+
-**Command Palette ni kama injini ya utafutaji kwa kila kitu unachoweza kufanya:**
-- Andika "open remote" na itapata kifungua hifadhi kwa ajili yako
-- Inakumbuka hifadhi ulizofungua hivi karibuni (ni muhimu sana!)
-- Ukizoea, utajisikia kama unafanya coding kwa kasi ya umeme
-- Ni kama "Hey Siri, lakini kwa coding" ya VSCode.dev
+**Komandi ya Palette ni kama kuwa na injini ya utafutaji ya kila jambo unaloweza kufanya:**
+- Andika "open remote" na itakupata kifungua hifadhidata
+- Inakumbuka hifadhidata ulizofungua hivi karibuni (ni rahisi sana!)
+- Ukizoea, utajisikia unavyotuma msimbo kwa kasi ya radi
+- Hii ni aina ya VSCode.dev ya "Hey Siri, lakini kwa kuandika msimbo"
-### Njia ya 2: Mbinu ya Kubadilisha URL
+### Njia ya 2: Mbinu ya Mabadiliko ya URL
-Kama vile HTTP na HTTPS zinavyotumia itifaki tofauti huku zikihifadhi muundo wa kikoa sawa, VSCode.dev hutumia muundo wa URL unaoakisi mfumo wa anwani wa GitHub. URL yoyote ya hifadhi ya GitHub inaweza kubadilishwa kufunguliwa moja kwa moja kwenye VSCode.dev.
+Kama vile HTTP na HTTPS wanavyotumia itifaki tofauti huku wakidumisha muundo wa kikoa sawa, VSCode.dev hutumia muundo wa URL unaoiga mfumo wa anwani za GitHub. URL yoyote ya hifadhidata ya GitHub inaweza kubadilishwa kufunguliwa moja kwa moja VSCode.dev.
-**Muundo wa mabadiliko ya URL:**
+**Mfano wa mabadiliko ya URL:**
-| Aina ya Hifadhi | URL ya GitHub | URL ya VSCode.dev |
-|------------------|---------------|-------------------|
-| **Hifadhi ya Umma** | `github.com/microsoft/Web-Dev-For-Beginners` | `vscode.dev/github/microsoft/Web-Dev-For-Beginners` |
-| **Mradi wa Kibinafsi** | `github.com/your-username/my-project` | `vscode.dev/github/your-username/my-project` |
-| **Hifadhi Yoyote Inayopatikana** | `github.com/their-username/awesome-repo` | `vscode.dev/github/their-username/awesome-repo` |
+| Aina ya Hifadhidata | URL ya GitHub | URL ya VSCode.dev |
+|----------------|---------------------|----------------|
+| **Hifadhidata ya Umma** | `github.com/microsoft/Web-Dev-For-Beginners` | `vscode.dev/github/microsoft/Web-Dev-For-Beginners` |
+| **Mradi Binafsi** | `github.com/your-username/my-project` | `vscode.dev/github/your-username/my-project` |
+| **Hifadhidata Ipo kwa Upatikanaji** | `github.com/their-username/awesome-repo` | `vscode.dev/github/their-username/awesome-repo` |
**Utekelezaji:**
-- Badilisha `github.com` na `vscode.dev/github`
-- Hifadhi vipengele vyote vya URL bila kubadilika
-- Inafanya kazi na hifadhi yoyote inayopatikana kwa umma
-- Hutoa ufikiaji wa haraka wa kuhariri
+- Badilisha `github.com` kuwa `vscode.dev/github`
+- Hifadhi sehemu zingine zote za URL bila kubadilika
+- Inaweza kufanya kazi na hifadhidata yoyote ya umma
+- Hutoa upatikanaji wa moja kwa moja wa kuhariri
-> 💡 **Kidokezo cha kubadilisha maisha**: Hifadhi matoleo ya VSCode.dev ya hifadhi zako unazozipenda. Nina alama za kurasa kama "Hariri Wasifu Wangu" na "Sahihisha Nyaraka" ambazo hunipeleka moja kwa moja kwenye hali ya kuhariri!
+> 💡 **Kidokezo cha kubadilisha maisha**: Weka alama za VSCode.dev za hifadhidata zako unazozipenda. Mimi nina alama kama "Hariri Miradi Yangu" na "Rekebisha Nyaraka" zinazonipeleka moja kwa moja kwenye hali ya kuhariri!
**Ni njia gani unapaswa kutumia?**
-- **Njia ya kiolesura**: Nzuri unapochunguza au huwezi kukumbuka majina halisi ya hifadhi
-- **Mbinu ya URL**: Bora kwa ufikiaji wa haraka unapojua hasa unakoenda
+- **Njia ya kiolesura**: Nzuri unapotafuta au hujui majina sahihi ya hifadhidata
+- **Mbinu ya URL**: Bora kwa upatikanaji wa haraka unapojua hasa mahali unapotaka kwenda
+
+### 🎯 Kagua Kujifunza: Upatikanaji wa Maendeleo ya Wingu
+
+**Simama na Fikiria**: Umejifunza njia mbili za kufikia hifadhidata kwa njia ya kivinjari. Hii ni mabadiliko makubwa katika jinsi maendeleo yanavyofanya kazi.
+
+**Tathmini Yako ya Haraka:**
+- Je, unaweza kuelezea kwa nini kuhariri mtandaoni huondoa hitaji la "usanidi wa mazingira ya maendeleo" ya kawaida?
+- Ni faida gani mbinu ya mabadiliko ya URL hutoa ikilinganishwa na kunakili git mahali poko?
+- Jinsi gani njia hii huhariri njia unavyoweza kuchangia miradi ya chanzo wazi?
+
+**Muunganisho wa Dunia Halisi**: Makampuni makubwa kama GitHub, GitLab, na Replit wamejenga jukwaa lao la maendeleo kwa misingi hii ya kihudumu wa wingu. Unajifunza mitiririko ile ile inayotumiwa na timu za maendeleo duniani kote.
+
+**Swali la Changamoto**: Maendeleo ya wingu yanaweza kubadilisha vipi jinsi kuandaliwa kwa kozi ya kuandika msimbo katika shule? Fikiria kuhusu mahitaji ya vifaa, usimamizi wa programu, na uwezekano wa kushirikiana.
## Kufanya Kazi na Faili na Miradi
-Sasa kwa kuwa umefungua hifadhi, hebu tuanze kujenga! VSCode.dev inakupa kila unachohitaji kuunda, kuhariri, na kupanga faili za nambari zako. Fikiria kama warsha yako ya kidijitali – kila zana iko mahali unapoihitaji.
+Sasa umefungua hifadhidata, hebu tuanze kujenga! VSCode.dev inakupatia kila kitu unachohitaji kuunda, kuhariri, na kupanga faili zako za msimbo. Fikiria kama warsha yako ya kidijitali – kila zana iko mahali unapotakiwa.
-Hebu tuingie kwenye kazi za kila siku ambazo zitaunda sehemu kubwa ya mtiririko wako wa kazi wa coding.
+Tuanze na kazi za kila siku zitakazokuwa sehemu kubwa ya mtiririko wako wa kuandika msimbo.
### Kuunda Faili Mpya
-Kama kupanga michoro katika ofisi ya mhandisi, uundaji wa faili katika VSCode.dev hufuata mbinu ya muundo. Mfumo huu unasaidia aina zote za faili za maendeleo ya wavuti.
+Kama kupanga ramani za majengo ofisini mwa mbuni wa majengo, uundaji wa faili ndani ya VSCode.dev hufuata mtindo ulio wazi. Mfumo unaunga mkono aina zote za kawaida za faili za maendeleo ya wavuti.
**Mchakato wa kuunda faili:**
-1. Nenda kwenye folda lengwa kwenye upau wa pembeni wa Explorer
-2. Elekeza juu ya jina la folda ili kufichua ikoni ya "Faili Mpya" (📄+)
-3. Ingiza jina la faili likijumuisha kiendelezi kinachofaa (`style.css`, `script.js`, `index.html`)
+1. Vinjari folda lengwa kwenye upande wa Explorer
+2. Lusua juu ya jina la folda kuonyesha ikoni ya "Faili Mpya" (📄+)
+3. Andika jina la faili pamoja na kiendelezi kinachofaa (`style.css`, `script.js`, `index.html`)
4. Bonyeza Enter kuunda faili
-
+
-**Misingi ya kutaja faili:**
-- Tumia majina yanayoelezea madhumuni ya faili
+**Kanuni za kuitia majina:**
+- Tumia majina ya kueleweka yanayoonyesha matumizi ya faili
- Jumuisha viendelezi vya faili kwa mwangaza sahihi wa sintaksia
-- Fuata mifumo thabiti ya kutaja faili katika miradi
-- Tumia herufi ndogo na alama za kuunganisha badala ya nafasi
+- Fuata mifumo ya majina thabiti katika miradi
+- Tumia herufi ndogo na mabano badala ya nafasi
### Kuhariri na Kuhifadhi Faili
-Hapa ndipo raha halisi inaanza! Mhariri wa VSCode.dev umejaa vipengele vya kusaidia vinavyofanya coding kuwa laini na ya angavu. Ni kama kuwa na msaidizi mzuri wa kuandika, lakini kwa nambari.
+Hapa ndipo furaha ya kweli inaanza! Mhariri wa VSCode.dev umejaa vipengele vya kusaidia vinavyofanya kuandika msimbo kuwa laini na ya kueleweka. Kama kuwa na msaidizi mahiri wa uandishi, lakini kwa msimbo.
**Mtiririko wako wa kuhariri:**
-1. Bonyeza faili yoyote kwenye Explorer ili kuifungua kwenye eneo kuu
-2. Anza kuandika na uone VSCode.dev ikikusaidia kwa rangi, mapendekezo, na kugundua makosa
-3. Hifadhi kazi yako kwa Ctrl+S (Windows/Linux) au Cmd+S (Mac) – ingawa inahifadhi kiotomatiki pia!
+1. Bonyeza faili yoyote kwenye Explorer kufungua katika eneo kuu
+2. Anza kuandika na uangalie VSCode.dev ikikuongezea rangi, mapendekezo, na kugundua makosa
+3. Hifadhi kazi kwa Ctrl+S (Windows/Linux) au Cmd+S (Mac) – ingawa huhifadhi moja kwa moja pia!
-
+
-**Mambo mazuri yanayotokea unapoandika nambari:**
-- Nambari yako inapata rangi nzuri ili iwe rahisi kusoma
-- VSCode.dev inapendekeza marekebisho unapoandika (kama autocorrect, lakini bora zaidi)
-- Inagundua makosa na makosa ya tahajia kabla hujahifadhi
-- Unaweza kuwa na faili nyingi wazi kwenye tabo, kama kwenye kivinjari
-- Kila kitu kinahifadhiwa kiotomatiki kwa nyuma
+**Mambo mazuri yanayotokea unapoandika msimbo:**
+- Msimbo wako unatolewa kwa rangi nzuri ili uwe rahisi kusoma
+- VSCode.dev inapendekeza mitiifu ya neno unaloteka (kama kusahihisha moja kwa moja, lakini zaidi intelligent)
+- Inakagua makosa kabla haujahifadhi
+- Unaweza kuwa na faili nyingi zikiwa wazi kwenye tabo tofauti, kama kwenye kivinjari
+- Kila kitu huhifadhiwa moja kwa moja nyuma ya pazia
-> ⚠️ **Kidokezo cha haraka**: Ingawa auto-save inakusaidia, kubonyeza Ctrl+S au Cmd+S bado ni tabia nzuri. Inahifadhi kila kitu mara moja na kuanzisha vipengele vingine vya kusaidia kama ukaguzi wa makosa.
+> ⚠️ **Kidokezo cha haraka**: Ingawa kuhifadhi moja kwa moja kuna msaada, kuzima Ctrl+S au Cmd+S bado ni desturi nzuri. Huhifadhi mara moja kila kitu na huanzisha vipengele vingine vya msaada kama ukaguzi wa makosa.
-### Udhibiti wa Toleo na Git
+### Udhibiti wa Matoleo kwa Git
-Kama vile wanakiolojia wanavyounda rekodi za kina za tabaka za uchimbaji, Git hufuatilia mabadiliko katika nambari yako kwa muda. Mfumo huu huhifadhi historia ya mradi na hukuwezesha kurudi kwenye matoleo ya awali unapohitaji. VSCode.dev inajumuisha utendaji wa Git.
+Kama wachimbaji wa kumbukumbu wanavyotengeneza kumbukumbu za kina za tabaka za kuchimba, Git hufuatilia mabadiliko kwenye msimbo wako kwa muda. Mfumo huu unahifadhi historia ya mradi na unakuwezesha kurudi kwa matoleo ya awali inapohitajika. VSCode.dev ina utendakazi wa Git uliounganishwa.
**Kiolesura cha Udhibiti wa Chanzo:**
-1. Fikia paneli ya Udhibiti wa Chanzo kupitia ikoni ya 🌿 kwenye Upau wa Shughuli
+1. Ingia kwenye paneli ya Udhibiti wa Chanzo kwa kutumia ikoni ya 🌿 kwenye Ukuta wa Shughuli
2. Faili zilizobadilishwa zinaonekana katika sehemu ya "Mabadiliko"
-3. Uwekaji rangi unaonyesha aina za mabadiliko: kijani kwa nyongeza, nyekundu kwa kufutwa
+3. Rangi hutambulisha aina za mabadiliko: kijani kwa nyongeza, nyekundu kwa ufutaji
-
+
-**Kuhifadhi kazi yako (mtiririko wa commit):**
+**Kuhifadhi kazi yako (mtiririko wa kufanya commit):**
```mermaid
flowchart TD
- A[Make changes to files] --> B[View changes in Source Control]
- B --> C[Stage changes by clicking +]
- C --> D[Write descriptive commit message]
- D --> E[Click checkmark to commit]
- E --> F[Changes pushed to GitHub]
+ A[Fanya mabadiliko kwenye faili] --> B[Tazama mabadiliko katika Udhibiti wa Chanzo]
+ B --> C[Tayarisha mabadiliko kwa kubofya +]
+ C --> D[Andika ujumbe wa kujitolea unaoelezea]
+ D --> E[Bonyeza alama ya kuangalia ili kujitolea]
+ E --> F[Mabadiliko yametumwa GitHub]
+```
+```mermaid
+stateDiagram-v2
+ [*] --> Modified: Hariri faili
+ Modified --> Staged: Bonyeza + kuweka hatua
+ Staged --> Modified: Bonyeza - kuondoa hatua
+ Staged --> Committed: Ongeza ujumbe & jitihada
+ Committed --> [*]: Sambaza kwenye GitHub
+
+ state Committed {
+ [*] --> LocalCommit
+ LocalCommit --> RemotePush: Sambaza kiotomatiki
+ }
```
-
**Hivi ndivyo unavyofanya hatua kwa hatua:**
-- Bonyeza ikoni ya "+" karibu na faili unazotaka kuhifadhi (hii inaziweka "staged")
-- Hakikisha kuwa unaridhika na mabadiliko yote yaliyowekwa
-- Andika maelezo mafupi yanayoelezea ulichofanya (hii ni "commit message" yako)
-- Bonyeza kitufe cha alama ya tiki ili kuhifadhi kila kitu kwenye GitHub
-- Ikiwa unabadili mawazo kuhusu kitu, ikoni ya kurudisha nyuma inakuruhusu kufuta mabadiliko
+- Bonyeza ikoni ya "+" kando ya faili unazotaka kuhifadhi (hii inawaita "kuweka awali" faili)
+- Hakikisha mara mbili kwamba umefurahishwa na mabadiliko yote yaliyopangwa
+- Andika noti fupi ikielezea ulichofanya (hii ni "ujumbe wako wa kujiwekea")
+- Bonyeza kitufe cha tiki kuhifadhi kila kitu kwenye GitHub
+- Ikiwa utabadilisha mawazo kuhusu jambo fulani, ikoni ya kufuta inakuwezesha kukataa mabadiliko
+
+**Kuandika ujumbe mzuri wa kujiwekea (hii ni rahisi kuliko unavyofikiri!):**
+- Elezea tu ulichofanya, kama "Ongeza fomu ya mawasiliano" au "Rekebisha urambazaji uliovunjika"
+- Fanya iwe fupi na nzuri – fikiria kama twiti, sio insha
+- Anza kwa maneno ya kitendo kama "Ongeza", "Rekebisha", "Sasisha", au "Ondoa"
+- **Mifano mizuri**: "Ongeza menyu ya urambazaji inayojibadilisha", "Rekebisha masuala ya muundo wa simu", "Sasisha rangi kwa ufikiaji bora"
-**Kuandika ujumbe mzuri wa commit (hii ni rahisi kuliko unavyofikiria!):**
-- Eleza tu ulichofanya, kama "Ongeza fomu ya mawasiliano" au "Sahihisha urambazaji uliovunjika"
-- Ifanye iwe fupi na rahisi – fikiria urefu wa tweet, si insha
-- Anza na maneno ya hatua kama "Ongeza", "Sahihisha", "Sasisha", au "Ondoa"
-- **Mifano mizuri**: "Ongeza menyu ya urambazaji inayojibika", "Sahihisha masuala ya mpangilio wa simu", "Sasisha rangi kwa upatikanaji bora"
+> 💡 **Kidokezo cha urambazaji haraka**: Tumia menyu ya hamburger (☰) juu kushoto kurudi kwenye hifadhi yako ya GitHub na kuona mabadiliko uliyojiwekea mtandaoni. Ni kama lango kati ya mazingira yako ya uhariri na nyumbani kwa mradi wako GitHub!
-> 💡 **Kidokezo cha urambazaji wa haraka**: Tumia menyu ya hamburger (☰) upande wa juu kushoto kurudi kwenye hifadhi yako ya GitHub na kuona mabadiliko yako yaliyohifadhiwa mtandaoni. Ni kama lango kati ya mazingira yako ya kuhariri na nyumbani kwa mradi wako kwenye GitHub!
+## Kuongeza Ufanisi Kwa Kuongeza Vipengele
+
+Kama vile duka la msanii linavyokuwa na zana maalum kwa kazi tofauti, VSCode.dev inaweza kuboreshwa kwa vipengele vinavyoongeza uwezo maalum. Viendelezaji waliotengenezwa na jamii hurekebisha mahitaji ya kawaida ya maendeleo kama vile upangaji wa msimbo, onyesho la moja kwa moja, na uunganisho bora wa Git.
+
+Soko la vipengele lina maelfu ya zana za bure zilizotengenezwa na watengenezaji duniani kote. Kila kiendelezaji hutatua changamoto maalum za mtiririko wa kazi, kukuwezesha kujenga mazingira ya maendeleo yaliyoongozwa na mahitaji yako binafsi na mapendeleo.
+
+```mermaid
+mindmap
+ root((Extension Ecosystem))
+ Essential Categories
+ Productivity
+ Live Server
+ Auto Rename Tag
+ Bracket Pair Colorizer
+ GitLens
+ Code Quality
+ Prettier
+ ESLint
+ Spell Checker
+ Error Lens
+ Language Support
+ HTML CSS Support
+ JavaScript ES6
+ Python Extension
+ Markdown Preview
+ Themes & UI
+ Dark+ Modern
+ Material Icon Theme
+ Peacock
+ Rainbow Brackets
+ Discovery Methods
+ Popular Rankings
+ Idadi za Kupakua
+ Ratings za Watumiaji
+ Sasisho za Karibuni
+ Mapitio ya Jamii
+ Recommendations
+ Mapendekezo ya Eneo la Kazi
+ Kulingana na Lugha
+ Kazi maalum ya Mtiririko
+ Viwango vya Timu
+```
+### Kupata Vipengele Vyako Kamili
-## Kuongeza Uwezo na Viendelezi
+Soko la vipengele limepangiliwa vyema, hivyo hutapotea ukitafuta unachohitaji. Limebuniwa kusaidia kugundua zana maalum na vitu vya kuvutia ambavyo haujajua vilikuwepo!
-Kama vile warsha ya fundi ina zana maalum kwa kazi tofauti, VSCode.dev inaweza kubinafsishwa na viendelezi vinavyoongeza uwezo maalum. Programu hizi zilizotengenezwa na jamii zinashughulikia mahitaji ya kawaida ya maendeleo kama uundaji wa nambari, mwonekano wa moja kwa moja, na ushirikiano ulioboreshwa wa Git.
+**Jinsi ya kufikia soko la vipengele:**
-Soko la viendelezi lina maelfu ya zana za bure zilizotengenezwa na watengenezaji kote ulimwenguni. Kila kiendelezi hutatua changamoto fulani za mtiririko wa kazi, ikiruhusu kujenga mazingira ya maendeleo yaliyobinafsishwa yanayofaa mahitaji na mapendeleo yako maalum.
+1. Bonyeza ikoni ya Vipengele (🧩) kwenye Upau wa Shughuli
+2. Vinjari au tafuta kitu maalum
+3. Bonyeza chochote kinachovutia kujifunza zaidi
-### Kupata Viendelezi Vyako Bora
+
-Soko la viendelezi limepangwa vizuri, kwa hivyo hutapotea ukijaribu kutafuta unachohitaji. Limeundwa kusaidia kugundua zana maalum na vitu vya kuvutia ambavyo hata hukujua vinapatikana!
+**Utakachoona humo:**
-**Kufikia soko:**
+| Sehemu | Kile Kilicho Ndani | Kwa Nini Ni Msaada |
+|----------|---------|----------|
+| **Imesakinishwa** | Vipengele ulivyoviongeza tayari | Zana zako binafsi za uandishi wa msimbo |
+| **Maarufu** | Vipendwa na wengi | Vilivyo maarufu kwa watengenezaji wengi |
+| **Inapendekezwa** | Mapendekezo mazuri kwa mradi wako | Mapendekezo ya msaada ya VSCode.dev |
-1. Bonyeza ikoni ya Viendelezi (🧩) kwenye Upau wa Shughuli
-2. Vin
-- Kila kiendelezi kinaonyesha alama za ukadiriaji, idadi ya upakuaji, na maoni ya watumiaji halisi
-- Unapata picha za skrini na maelezo wazi ya kile kila moja inafanya
-- Kila kitu kimewekwa alama wazi na taarifa za ulinganifu
-- Viendelezi vinavyofanana vinapendekezwa ili uweze kulinganisha chaguo
+**Kile kinachofanya urambazaji kuwa rahisi:**
+- Kila kiendelezaji kina viwango, idadi ya pakizi, na maoni halisi ya watumiaji
+- Unapata picha na maelezo wazi ya kile kila kimoja hufanya
+- Kila kitu kimeainishwa kwa uwazi na taarifa ya ulinganifu
+- Vipengele vinavyofanana vinapendekezwa ili ulinganishe chaguzi
-### Kusakinisha Viendelezi (Ni Rahisi Sana!)
+### Kusakinisha Vipengele (Ni Rahisi Sana!)
-Kuongeza nguvu mpya kwenye mhariri wako ni rahisi kama kubonyeza kitufe. Viendelezi husakinishwa kwa sekunde na kuanza kufanya kazi mara moja – hakuna kuanzisha upya, hakuna kusubiri.
+Kuwaongeza nguvu mpya mhariri wako ni rahisi kama kubonyeza kitufe. Vipengele husakinishwa kwa sekunde na kuanza kufanya kazi mara moja – hakuna kuanzisha upya, hakuna kusubiri.
-**Hivi ndivyo unavyopaswa kufanya:**
+**Hivi ndivyo unavyofanya:**
1. Tafuta unachotaka (jaribu kutafuta "live server" au "prettier")
-2. Bonyeza kile kinachoonekana kizuri ili kuona maelezo zaidi
-3. Soma kile kinachofanya na angalia alama za ukadiriaji
-4. Bonyeza kitufe cha bluu "Install" na umemaliza!
+2. Bonyeza kile kinachoonekana kizuri kuona maelezo zaidi
+3. Soma kuhusu kile hufanya na angalia viwango
+4. Bonyeza kitufe cha buluu cha "Install" na umemaliza!
-
+
**Kinachotokea nyuma ya pazia:**
-- Kiendelezi kinapakuliwa na kujisakinisha kiotomatiki
-- Vipengele vipya vinaonekana kwenye kiolesura chako mara moja
-- Kila kitu kinaanza kufanya kazi mara moja (kweli, ni haraka hivyo!)
-- Ikiwa umeingia, kiendelezi kinasawazishwa kwenye vifaa vyako vyote
+- Kiendelezaji hupakuliwa na kujiseti moja kwa moja
+- Vipengele vipya vinaonekana katika kiolesura chako mara moja
+- Kila kitu kinaanza kufanya kazi papo hapo (kwa kweli, ni haraka hivyo!)
+- Ikiwa umeingia kwenye akaunti, kiendelezaji kinalinganisha vifaa vyako vyote
-**Baadhi ya viendelezi ninavyopendekeza kuanza navyo:**
-- **Live Server**: Tazama tovuti yako ikisasishwa moja kwa moja unapoandika (hiki ni cha kichawi!)
-- **Prettier**: Hufanya msimbo wako uonekane safi na wa kitaalamu kiotomatiki
-- **Auto Rename Tag**: Badilisha tagi moja ya HTML na mwenza wake pia anasasishwa
-- **Bracket Pair Colorizer**: Inaweka rangi kwenye mabano yako ili usipotee
-- **GitLens**: Inaongeza nguvu kwenye vipengele vyako vya Git na taarifa nyingi za msaada
+**Vipengele vingine ninavyopendekeza kuanzia navyo:**
+- **Live Server**: Tazama tovuti yako ikibadilika kwa wakati halisi unapotengeneza (hiki ni cha kishangaza!)
+- **Prettier**: Hufanya msimbo wako kuwa safi na wa kitaalamu moja kwa moja
+- **Auto Rename Tag**: Badilisha lebo moja ya HTML na mshirika wake hubadilika pia
+- **Bracket Pair Colorizer**: Rangi mabano yako ili usipotee kabisa
+- **GitLens**: Inaongeza nguvu kwa vipengele vya Git na taarifa nyingi za msaada
-### Kubinafsisha Viendelezi Vyako
+### Kubinafsisha Vipengele Vyako
-Viendelezi vingi vina mipangilio unayoweza kurekebisha ili kufanya vifanye kazi jinsi unavyopenda. Fikiria kama kurekebisha kiti na vioo kwenye gari – kila mtu ana mapendeleo yake!
+Vipengele vingi huja na mipangilio unayoweza kubadilisha ili kufanya kazi jinsi unavyotaka. Fikiria kama kurekebisha kiti na vioo ndani ya gari – kila mtu ana mapendeleo yake!
-**Kurekebisha mipangilio ya kiendelezi:**
+**Kurekebisha mipangilio ya kiendelezaji:**
-1. Tafuta kiendelezi chako kilichosakinishwa kwenye paneli ya Viendelezi
-2. Tafuta ikoni ndogo ya gia (⚙️) karibu na jina lake na bonyeza
-3. Chagua "Extension Settings" kutoka kwenye menyu ya kushuka
-4. Rekebisha mambo hadi yahisi sawa na mtiririko wako wa kazi
+1. Pata kiendelezaji ulichosakinisha kwenye paneli ya Vipengele
+2. Tafuta ikoni ya gia ndogo (⚙️) kando ya jina lake na bonyeza
+3. Chagua "Extension Settings" kutoka kwenye menyu ya kushuka chini
+4. Rekebisha vitu hadi viwe vinakufaa kabisa kwa mtiririko wako wa kazi
-
+
-**Mambo ya kawaida unayoweza kutaka kurekebisha:**
-- Jinsi msimbo wako unavyopangwa (tabu dhidi ya nafasi, urefu wa mistari, nk.)
-- Vifupisho vya kibodi vinavyosababisha vitendo tofauti
-- Aina gani za faili kiendelezi kinapaswa kufanya kazi nazo
-- Kuwasha au kuzima vipengele maalum ili kuweka mambo safi
+**Vitu vya kawaida ambavyo unaweza kutaka kubadilisha:**
+- Jinsi msimbo wako unavyoandaliwa (taps vs nafasi, urefu wa mstari, n.k.)
+- Ni vitufe gani vya kibodi vinavyochochea vitendo tofauti
+- Aina ya faili ambazo kiendelezaji kinapaswa kufanya nao kazi
+- Kuzima au kuwasha vipengele maalum ili kuweka kila kitu safi
-### Kuweka Viendelezi Vyako Vizuri
+### Kuweka Vipengele Vyako Katika Mpangilio
-Unapogundua viendelezi zaidi vya kuvutia, utataka kuweka mkusanyiko wako safi na unaofanya kazi vizuri. VSCode.dev inafanya hili kuwa rahisi sana kusimamia.
+Unapogundua vipengele zaidi vya kuvutia, utataka kuweka mkusanyiko wako katika mpangilio mzuri na kuendesha vizuri. VSCode.dev inafanya hili kuwa rahisi sana kusimamia.
-**Chaguo zako za usimamizi wa viendelezi:**
+**Chaguzi zako za usimamizi wa vipengele:**
-| Unachoweza Kufanya | Wakati Inapokuwa Msaada | Kidokezo cha Mtaalamu |
+| Unaweza Kufanya Nini | Linapokuwa Msaada | Kumbukumbu ya Mtaalamu |
|--------|---------|----------|
-| **Disable** | Kuangalia kama kiendelezi kinasababisha matatizo | Bora kuliko kuondoa ikiwa unaweza kutaka kurudisha |
-| **Uninstall** | Kuondoa kabisa viendelezi usivyohitaji | Huweka mazingira yako safi na haraka |
-| **Update** | Kupata vipengele vipya na marekebisho ya hitilafu | Kawaida hufanyika kiotomatiki, lakini ni vyema kuangalia |
+| **Zima** | Kupima ikiwa kiendelezaji kinayosababisha matatizo | Bora kuliko kuondoa ikiwa ungetaka kurudisha baadaye |
+| **Ondoa** | Kuondoa kabisa vipengele usivihitaji | Huweka mazingira yako safi na ya kasi |
+| **Sasisha** | Kupata vipengele na marekebisho ya hitilafu mpya | Kawaida hufanyika moja kwa moja, lakini ni vyema kuangalia |
+
+**Jinsi ninavyopenda kusimamia vipengele:**
+- Kila miezi michache, hupitia kile nilicho nacho na kuondoa visivyotumika
+- Ninasasisha vipengele ili kupata maboresho mapya na marekebisho ya usalama
+- Ikiwa kitu kinaonekana cha polepole, huwasha au kuzima kwa muda vipengele kuona kama kilikuwa chanzo
+- Ninasoma maelezo ya sasisho wakati vipengele vinapopata maboresho makubwa – wakati mwingine kuna vipengele vipya vya kuvutia!
+
+> ⚠️ **Kidokezo cha utendaji**: Vipengele ni vya ajabu, lakini kuwa na nyingi sana kunaweza kuharakisha mfumo. Lenga kwenye zile zinazokuongeza maisha rahisi na usiogope kuondoa zile ambazo hutumiwi kamwe.
+
+### 🎯 Ukaguzi wa Kifundisho: Urekebishaji wa Mazingira ya Maendeleo
+
+**Uelewa wa Miundo**: Umejifunza kubinafsisha mazingira ya kitaalamu ya maendeleo kwa kutumia vipengele vilivyotengenezwa na jamii. Hii inaendana na jinsi timu za maendeleo za makampuni zinavyotengeneza zana za kawaida.
+
+**Mada Muhimu Uliyothibitisha**:
+- **Ugunduzi wa Vipengele**: Kupata zana zinazotatua changamoto maalum za maendeleo
+- **Usanidi wa Mazingira**: Kubinafsisha zana kufuata mapendeleo binafsi au timu
+- **Uboreshaji wa Utendaji**: Kuweka uwiano kati ya ufanisi na utendaji wa mfumo
+- **Ushirikiano wa Jamii**: Kutumia zana zilizo tengenezwa na jamii ya watengenezaji duniani
-**Jinsi ninavyopenda kusimamia viendelezi:**
-- Kila miezi michache, ninapitia nilichosakinisha na kuondoa chochote nisichotumia
-- Ninaweka viendelezi vikiwa vimesasishwa ili nipate maboresho ya hivi karibuni na marekebisho ya usalama
-- Ikiwa kitu kinaonekana kuwa polepole, ninazima viendelezi kwa muda ili kuona kama moja yao ndiyo sababu
-- Ninasoma maelezo ya sasisho wakati viendelezi vinapata sasisho kubwa – wakati mwingine kuna vipengele vipya vya kuvutia!
+**Uhusiano wa Sekta**: Mifumo ya vipengele ndio nguvu ya majukwaa makubwa ya maendeleo kama VS Code, Chrome DevTools, na IDE za kisasa. Kuelewa jinsi ya kutathmini, kusakinisha, na kusanidi vipengele ni muhimu kwa mtiririko wa kazi wa kitaalamu.
+
+**Swali la Tafakari**: Ungedhibiti vipi kuanzisha mazingira ya maendeleo yaliyosawazishwa kwa timu ya watengenezaji 10? Fikiria kuhusu utofauti, utendaji, na mapendeleo binafsi.
+
+## 📈 Ratiba Yako ya Uwezo wa Maendeleo ya Wingu
+
+```mermaid
+timeline
+ title Safari ya Uendelezaji wa Wingu ya Kitaalamu
+
+ section Misingi ya Jukwaa
+ Uelewa wa Uendelezaji wa Wingu
+ : Jifunze dhana za uhariri mtandaoni
+ : Unganisha mifumo ya uunganishaji wa GitHub
+ : Panda kutumia maeneo ya kitaalamu
+
+ section Uwezo wa Kazi
+ Usimamizi wa Faili & Miradi
+ : Tengeneza miundo ya mradi uliopangwa
+ : Jifunze manufaa ya kuonyesha sentensi
+ : Simamia michakato ya uhariri wa faili nyingi
+
+ Uunganishaji wa Udhibiti wa Toleo
+ : Elewa uonyesha wa Git
+ : Fanya mazoezi ya viwango vya ujumbe wa commit
+ : Jifunze michakato ya kufuatilia mabadiliko
+
+ section Ubinafsishaji wa Mazingira
+ Eneo la Upanuzi
+ : Gundua virutubisho vya tija
+ : Sanidi mapendeleo ya ukuzaji
+ : Boresha utendaji vs utendakazi
+
+ Usanidi wa Kitaalamu
+ : Tengeneza michakato thabiti
+ : Tengeneza usanidi unaoweza kutumika tena
+ : Weka viwango vya timu
+
+ section Utaalamu wa Sekta
+ Uendelezaji wa Kwanza Wingu
+ : Jifunze mazoea ya ukuzaji wa mbali
+ : Elewa michakato ya ushirikiano
+ : Jenga ujuzi huru wa jukwaa
+
+ Mazoezi ya Kitaalamu
+ : Fuata viwango vya sekta
+ : Tengeneza michakato inayoweza kudumishwa
+ : Jiandae kwa mazingira ya timu
+```
+**🎓 Hatua ya Kuajiliwa**: Umefanikiwa kukamilisha maendeleo ya wingu kwa kutumia zana na mtiririko huo huo unaotumiwa na watengenezaji wa kitaalamu katika makampuni makubwa ya teknolojia. Hizi ni stadi za mustakabali wa maendeleo ya programu.
-> ⚠️ **Kidokezo cha Utendaji**: Viendelezi ni vya ajabu, lakini kuwa na vingi sana vinaweza kupunguza kasi ya mambo. Zingatia vile vinavyokufanya maisha yako kuwa rahisi na usisite kuondoa vile usivyotumia.
+**🔄 Uwezo wa Ngazi Ifuatayo**:
+- Tayari kuchunguza majukwaa ya maendeleo ya wingu ya hali ya juu (Codespaces, GitPod)
+- Tayari kufanya kazi katika timu za maendeleo zilizoenea
+- Umebeba uwezo wa kuchangia miradi ya chanzo huria duniani
+- Msingi umejengwa kwa mbinu za kisasa za DevOps na ujumuishaji endelevu
## Changamoto ya Wakala wa GitHub Copilot 🚀
-Kama mbinu iliyopangwa ambayo NASA hutumia kwa misheni za anga, changamoto hii inahusisha matumizi ya kimfumo ya ujuzi wa VSCode.dev katika hali kamili ya mtiririko wa kazi.
+Kama vile NASA inavyotumia mbinu ya muundo kwa misheni za anga za juu, changamoto hii inahusisha matumizi ya kitaalamu ya ujuzi wa VSCode.dev katika hali kamili ya mtiririko wa kazi.
-**Lengo:** Onyesha ustadi na VSCode.dev kwa kuanzisha mtiririko wa kazi wa maendeleo ya wavuti.
+**Lengo:** Onyesha ufanisi na VSCode.dev kwa kuanzisha mtiririko kamili wa maendeleo ya wavuti.
-**Mahitaji ya mradi:** Kwa kutumia msaada wa hali ya Wakala, kamilisha majukumu haya:
-1. Fork hifadhi iliyopo au unda mpya
+**Mahitaji ya mradi:** Kwa msaada wa hali ya Wakala, kamilisha kazi hizi:
+1. Fanya nakala ya hifadhi iliyopo au unda mpya
2. Anzisha muundo wa mradi unaofanya kazi na faili za HTML, CSS, na JavaScript
-3. Sakinisha na sanidi viendelezi vitatu vinavyoongeza maendeleo
-4. Fanya udhibiti wa toleo na ujumbe wa maelezo ya commit
-5. Jaribu kuunda na kurekebisha matawi ya vipengele
+3. Sakinisha na sanidi vipengele vitatu vinavyoongeza maendeleo
+4. Fanya mazoezi ya udhibiti wa toleo kwa ujumbe wa maelezo wa kujiwekea
+5. Jaribu kuunda na kubadilisha matawi ya kipengele
6. Andika mchakato na mafunzo katika faili ya README.md
-Zoezi hili linajumuisha dhana zote za VSCode.dev katika mtiririko wa kazi wa vitendo ambao unaweza kutumika kwa miradi ya maendeleo ya baadaye.
+Mazoezi haya yanakusanya dhana zote za VSCode.dev katika mtiririko wa kazi wa vitendo unaoweza kutumika kwa miradi ya maendeleo yajayo.
Jifunze zaidi kuhusu [hali ya wakala](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode) hapa.
## Kazi
-Ni wakati wa kujaribu ujuzi huu kwa vitendo! Nina mradi wa vitendo utakao kuruhusu kufanya mazoezi ya kila kitu tulichojadili: [Tengeneza tovuti ya wasifu kwa kutumia VSCode.dev](./assignment.md)
+Wakati wa kutumia ujuzi huu kwa mtihani halisi! Nina mradi wa vitendo utakayokuwezesha kufanya mazoezi ya kila kitu tulichojifunza: [Unda tovuti ya wasifu kwa kutumia VSCode.dev](./assignment.md)
-Kazi hii inakuelekeza jinsi ya kujenga tovuti ya wasifu wa kitaalamu kabisa kwenye kivinjari chako. Utatumia vipengele vyote vya VSCode.dev tulivyovijadili, na mwishoni, utakuwa na tovuti nzuri na ujasiri thabiti katika mtiririko wako mpya wa kazi.
+Kazi hii itakuongoza kujenga tovuti ya kitaalamu ya wasifu kabisa kwa kutumia kivinjari chako. Utatumia sifa zote za VSCode.dev tulizochunguza, na mwishoni utakuwa na tovuti nzuri pamoja na uhakika imara katika mtiririko wako mpya wa kazi.
## Endelea Kuchunguza na Kuongeza Ujuzi Wako
-Sasa una msingi mzuri, lakini kuna mambo mengi zaidi ya kuvutia ya kugundua! Hapa kuna rasilimali na mawazo ya kukuza ujuzi wako wa VSCode.dev:
+Umejenga msingi mzuri sasa, lakini kuna mambo mengi ya kuvutia zaidi ya kugundua! Hapa ni baadhi ya rasilimali na mawazo ya kuinua ujuzi wako wa VSCode.dev hadi ngazi inayofuata:
-**Nyaraka rasmi zinazofaa kuwekwa alama:**
-- [Nyaraka za VSCode Web](https://code.visualstudio.com/docs/editor/vscode-web?WT.mc_id=academic-0000-alfredodeza) – Mwongozo kamili wa kuhariri kwa kutumia kivinjari
-- [GitHub Codespaces](https://docs.github.com/en/codespaces) – Kwa wakati unapotaka nguvu zaidi kwenye wingu
+**Nyaraka rasmi za kuenzi:**
+- [Nyaraka za Mtandao wa VSCode](https://code.visualstudio.com/docs/editor/vscode-web?WT.mc_id=academic-0000-alfredodeza) – Mwongozo kamili wa kuhariri kwenye kivinjari
+- [GitHub Codespaces](https://docs.github.com/en/codespaces) – Kwa wakati unapotaka nguvu zaidi katika wingu
-**Vipengele vya kuvutia vya kujaribu baadaye:**
-- **Vifupisho vya Kibodi**: Jifunze mchanganyiko wa funguo utakufanya uhisi kama ninja wa msimbo
-- **Mipangilio ya Workspace**: Sanidi mazingira tofauti kwa aina tofauti za miradi
-- **Multi-root Workspaces**: Fanya kazi kwenye hifadhi nyingi kwa wakati mmoja (inasaidia sana!)
-- **Ujumuishaji wa Terminal**: Fikia zana za mstari wa amri moja kwa moja kwenye kivinjari chako
+**Vipengele vya kufurahisha vya kujaribu baadaye:**
+- **Mifungo ya Kibodi**: Jifunze mchanganyiko wa funguo utakayohisi kama mtaalamu wa kuandika msimbo
+- **Mipangilio ya Eneo la Kazi**: Andaa mazingira tofauti kwa aina tofauti za miradi
+- **Mazingira ya Kazi ya Msingi Mwingi**: Fanya kazi kwenye hifadhi nyingi kwa wakati mmoja (ni rahisi sana!)
+- **Uunganisho wa Terminal**: Pata zana za mstari wa amri moja kwa moja kwenye kivinjari chako
**Mawazo ya kufanya mazoezi:**
-- Jiunge na miradi ya chanzo huria na uchangie ukitumia VSCode.dev – ni njia nzuri ya kurudisha!
-- Jaribu viendelezi tofauti ili kupata mpangilio wako bora
-- Unda templeti za miradi kwa aina za tovuti unazojenga mara nyingi
-- Fanya mazoezi ya mtiririko wa kazi wa Git kama kuunda matawi na kuunganisha – ujuzi huu ni dhahabu katika miradi ya timu
+- Jitose kwenye miradi ya chanzo huria na changia kwa kutumia VSCode.dev – ni njia nzuri ya kutoa msaada!
+- Jaribu vipengele tofauti kutafuta mpangilio wako kamili
+- Unda templeti za miradi kwa aina za tovuti unazojenga mara nyingi zaidi
+- Fanya mazoezi ya mikondo ya Git kama matawi na mchanganyiko – hizi ni dhahabu kwa miradi ya timu
---
-**Umebobea katika maendeleo ya msingi wa kivinjari!** 🎉 Kama jinsi uvumbuzi wa vyombo vinavyobebeka uliruhusu wanasayansi kufanya utafiti katika maeneo ya mbali, VSCode.dev inawezesha usimbaji wa kitaalamu kutoka kwa kifaa chochote chenye muunganisho wa intaneti.
+**Umeshinda maendeleo ya kivinjari!** 🎉 Kama vile uvumbuzi wa vyombo vinavyobebwa ulivyoruhusu wanasayansi kufanya utafiti katika maeneo ya mbali, VSCode.dev inakuwezesha kuandika msimbo kitaaluma kutoka kifaa chochote kilichounganishwa na intaneti.
-Ujuzi huu unaakisi mazoea ya sasa ya sekta – watengenezaji wengi wa kitaalamu hutumia mazingira ya maendeleo ya msingi wa wingu kwa kubadilika na upatikanaji wake. Umejifunza mtiririko wa kazi unaoweza kupanuka kutoka miradi ya mtu binafsi hadi ushirikiano wa timu kubwa.
+Stadi hizi zinaonyesha mbinu za sasa za sekta – watengenezaji wengi wa kitaalamu hutumia mazingira ya maendeleo ya wingu kwa ugumu na upatikanaji wake. Umejifunza mtiririko wa kazi unaobadilika kutoka kwenye miradi ya mtu binafsi hadi ushirikiano mkubwa wa timu.
-Tumia mbinu hizi kwenye mradi wako wa maendeleo unaofuata! 🚀
+Tumia mbinu hizi kwa mradi wako unaofuata wa maendeleo! 🚀
---
-**Kanusho**:
-Hati hii imetafsiriwa kwa kutumia huduma ya kutafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kwa usahihi, tafadhali fahamu kuwa tafsiri za kiotomatiki zinaweza kuwa na makosa au kutokuwa sahihi. Hati ya asili katika lugha yake ya awali inapaswa kuzingatiwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya kitaalamu ya binadamu inapendekezwa. Hatutawajibika kwa kutoelewana au tafsiri zisizo sahihi zinazotokana na matumizi ya tafsiri hii.
\ No newline at end of file
+
+**Tangazo la Kukataa**:
+Nyaraka hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kwa usahihi, tafadhali fahamu kuwa tafsiri za kiotomatiki zinaweza kuwa na makosa au kasoro. Nyaraka asili katika lugha yake ya asili inapaswa kuchukuliwa kama chanzo halali. Kwa taarifa muhimu, tafsiri ya kitaalamu inayofanywa na binadamu inashauriwa. Hatuwajibiki kwa kutokuelewana au tafsiri potofu zinazotokana na matumizi ya tafsiri hii.
+
\ No newline at end of file
diff --git a/translations/sw/8-code-editor/1-using-a-code-editor/assignment.md b/translations/sw/8-code-editor/1-using-a-code-editor/assignment.md
index 057be3245..249fd020c 100644
--- a/translations/sw/8-code-editor/1-using-a-code-editor/assignment.md
+++ b/translations/sw/8-code-editor/1-using-a-code-editor/assignment.md
@@ -78,7 +78,7 @@ Kwa kuwa VSCode.dev inahitaji angalau faili moja kufungua hifadhi, tutaunda fail
4. **Andika** ujumbe wa kujitolea: "Ongeza muundo wa awali wa HTML"
5. **Bonyeza** "Commit new file" ili kuhifadhi mabadiliko yako
-
+
**Hiki ndicho uanzishaji huu wa awali unakamilisha:**
- **Unaunda** muundo sahihi wa hati ya HTML5 na vipengele vya kimantiki
@@ -104,7 +104,7 @@ Sasa kwa kuwa msingi wa hifadhi yako umeanzishwa, hebu tubadilishe kwa VSCode.de
✅ **Kiashiria cha mafanikio**: Unapaswa kuona faili za mradi wako kwenye upau wa kando wa Explorer na `index.html` ikipatikana kwa kuhariri kwenye eneo kuu la mhariri.
-
+
**Unachokiona kwenye kiolesura:**
- **Upau wa kando wa Explorer**: **Unaonyesha** faili za hifadhi yako na muundo wa folda
@@ -448,7 +448,7 @@ Viendelezi vinaboresha uzoefu wako wa maendeleo kwa kutoa uwezo wa hakikisho la
**Matokeo ya haraka baada ya usakinishaji:**
Mara tu CodeSwing itakaposakinishwa, utaona hakikisho la moja kwa moja la tovuti yako ya resume likijitokeza kwenye mhariri. Hii inakuwezesha kuona jinsi tovuti yako inavyoonekana unavyofanya mabadiliko.
-
+
**Kuelewa kiolesura kilichoboreshwa:**
- **Muonekano wa mgawanyiko**: **Unaonyesha** msimbo wako upande mmoja na hakikisho la moja kwa moja upande mwingine
diff --git a/translations/sw/9-chat-project/README.md b/translations/sw/9-chat-project/README.md
index 1eef189a3..47f8497cf 100644
--- a/translations/sw/9-chat-project/README.md
+++ b/translations/sw/9-chat-project/README.md
@@ -1,102 +1,213 @@
-# Jinsi ya Kujenga Msaidizi wa Mazungumzo kwa Kutumia AI
+# Jenga Msaidizi wa Chat kwa AI
-Unakumbuka kwenye Star Trek jinsi wafanyakazi walivyokuwa wakiongea na kompyuta ya meli, wakiuliza maswali magumu na kupata majibu ya kina? Kile kilichoonekana kama hadithi ya kisayansi katika miaka ya 1960 sasa ni kitu unachoweza kujenga kwa kutumia teknolojia za mtandao unazozijua tayari.
+Kumbuka kwenye Star Trek wanapotumia mazungumzo ya kawaida na kompyuta ya meli, wakimuuliza maswali magumu na kupata majibu yenye fikira? Kinachokuwa kama hadithi ya sayansi katika miaka ya 1960 sasa ni kitu ambacho unaweza kujenga kwa kutumia teknolojia za wavuti unazozijua tayari.
-Katika somo hili, tutatengeneza msaidizi wa mazungumzo wa AI kwa kutumia HTML, CSS, JavaScript, na muunganisho wa nyuma. Utajifunza jinsi ujuzi ule ule unaojifunza unaweza kuunganishwa na huduma za AI zenye uwezo wa kuelewa muktadha na kutoa majibu yenye maana.
+Katika somo hili, tutaunda msaidizi wa AI wa mazungumzo kwa kutumia HTML, CSS, JavaScript, na muunganisho wa nyuma. Utagundua jinsi ujuzi ule ule ambao umekuwa ukijifunza unaweza kuunganishwa na huduma zenye nguvu za AI ambazo zinaweza kuelewa muktadha na kutoa majibu yenye maana.
-Fikiria AI kama kuwa na ufikiaji wa maktaba kubwa ambayo si tu inapata taarifa bali pia inazichanganya kuwa majibu yanayofaa kulingana na maswali yako maalum. Badala ya kutafuta kupitia maelfu ya kurasa, unapata majibu ya moja kwa moja na ya muktadha.
+Fikiria AI kama kuwa na upatikanaji wa maktaba kubwa ambayo si tu inatafuta taarifa bali pia inaunda majibu yaliyo na maelezo yaliyounganishwa na maswali yako maalum. Badala ya kutafuta kupitia maelfu ya kurasa, unapata majibu ya moja kwa moja na yenye muktadha.
-Muunganisho unafanyika kupitia teknolojia za mtandao zinazofanya kazi pamoja. HTML inaunda kiolesura cha mazungumzo, CSS inashughulikia muundo wa kuona, JavaScript inasimamia mwingiliano wa mtumiaji, na API ya nyuma inaunganisha kila kitu na huduma za AI. Ni sawa na jinsi sehemu tofauti za orchestra zinavyofanya kazi pamoja kuunda symphony.
+Muunganisho hufanyika kupitia teknolojia za wavuti zinazojulikana zinazofanya kazi pamoja. HTML huunda kiolesura cha mazungumzo, CSS hushughulikia muundo wa kuona, JavaScript inasimamia mwingiliano wa mtumiaji, na API ya nyuma inaunganisha kila kitu na huduma za AI. Hii ni sawa na jinsi sehemu tofauti za orkesta zinavyofanya kazi pamoja kuunda sinfonia.
-Kimsingi tunajenga daraja kati ya mawasiliano ya kawaida ya binadamu na usindikaji wa mashine. Utajifunza utekelezaji wa kiufundi wa muunganisho wa huduma za AI na mifumo ya muundo inayofanya mwingiliano kuwa wa kawaida.
+Kwa msingi, tunajenga daraja kati ya mawasiliano ya asili ya binadamu na usindikaji wa mashine. Utajifunza utekelezaji wa kiufundi wa muunganisho wa huduma za AI na mifumo ya muundo inayofanya mwingiliano hisike kwa njia ya asili.
-Mwisho wa somo hili, muunganisho wa AI hautahisi kama mchakato wa ajabu bali kama API nyingine unayoweza kufanya kazi nayo. Utaelewa mifumo ya msingi inayowezesha programu kama ChatGPT na Claude, kwa kutumia kanuni zile zile za maendeleo ya mtandao unazojifunza.
+Mwisho wa somo hili, muunganisho wa AI utakuhisi si kama mchakato wa ajabu bali kama API nyingine unayoweza kutumia. Utatafuta mifumo ya msingi inayochochea programu kama ChatGPT na Claude, ukitumia kanuni zile zile za maendeleo ya wavuti ulizojifunza.
-Hivi ndivyo mradi wako wa mwisho utakavyoonekana:
+## ⚡ Unaweza Kufanya Nini Katika Dakika 5 Zijazo
-
+**Njia ya Kuanzisha Haraka kwa Waendelezaji Walioko Mbusy**
-## Kuelewa AI: Kutoka Siri hadi Ustadi
+```mermaid
+flowchart LR
+ A[⚡ Dakika 5] --> B[Pata tokeni ya GitHub]
+ B --> C[Jaribu uwanja wa michezo wa AI]
+ C --> D[Nakili msimbo wa Python]
+ D --> E[Tazama majibu ya AI]
+```
+- **Dakika 1**: Tembelea [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) na tengeneza tokeni ya upatikanaji binafsi
+- **Dakika 2**: Jaribu mwingiliano wa AI moja kwa moja kwenye kiolesura cha playground
+- **Dakika 3**: Bonyeza kichupo cha "Code" na nakili kipande cha Python
+- **Dakika 4**: Endesha msimbo kwa ndani kwa kutumia tokeni yako: `GITHUB_TOKEN=your_token python test.py`
+- **Dakika 5**: Tazama jibu lako la kwanza la AI likiundwa kutoka kwa msimbo wako mwenyewe
-Kabla ya kuingia kwenye msimbo, hebu tuelewe tunachofanya kazi nacho. Ikiwa umewahi kutumia API, unajua muundo wa msingi: tuma ombi, pokea jibu.
+**Msimbo wa Jaribio la Haraka**:
+```python
+import os
+from openai import OpenAI
-API za AI zinafuata muundo sawa, lakini badala ya kupata data iliyohifadhiwa kutoka kwenye hifadhidata, zinazalisha majibu mapya kulingana na mifumo iliyojifunza kutoka kwa maandishi mengi. Fikiria kama tofauti kati ya mfumo wa katalogi ya maktaba na mtaalamu wa maktaba anayejua kuchanganya taarifa kutoka vyanzo mbalimbali.
+client = OpenAI(
+ base_url="https://models.github.ai/inference",
+ api_key="your_token_here"
+)
-### "Generative AI" ni Nini Haswa?
+response = client.chat.completions.create(
+ messages=[{"role": "user", "content": "Hello AI!"}],
+ model="openai/gpt-4o-mini"
+)
-Fikiria jinsi Jiwe la Rosetta lilivyowezesha wasomi kuelewa hieroglyphics za Misri kwa kutafuta mifumo kati ya lugha zinazojulikana na zisizojulikana. Miundo ya AI inafanya kazi kwa njia sawa – inatafuta mifumo katika maandishi mengi ili kuelewa jinsi lugha inavyofanya kazi, kisha kutumia mifumo hiyo kutoa majibu yanayofaa kwa maswali mapya.
+print(response.choices[0].message.content)
+```
+
+**Kwa Nini Hii ni Muhimu**: Ndani ya dakika 5, utaona uchawi wa mwingiliano wa AI kwa programu. Hii inaonyesha kizuizi cha msingi kinachochochea kila programu ya AI unayotumia.
+
+Hivi ndivyo mradi wako utakavyoonekana umemalizika:
-**Hebu niweke wazi kwa kulinganisha rahisi:**
-- **Hifadhidata ya jadi**: Kama kuuliza cheti chako cha kuzaliwa – unapata hati ile ile kila wakati
-- **Injini ya utafutaji**: Kama kuuliza mtaalamu wa maktaba kutafuta vitabu kuhusu paka – wanakuonyesha kilichopo
-- **Generative AI**: Kama kuuliza rafiki mwenye ujuzi kuhusu paka – wanakuambia mambo ya kuvutia kwa maneno yao wenyewe, kulingana na unachotaka kujua
+
+
+## 🗺️ Safari Yako ya Kujifunza Kupitia Maendeleo ya Programu za AI
+
+```mermaid
+journey
+ title Kutoka Maendeleo ya Wavuti hadi Muunganiko wa AI
+ section Kuelewa Misingi ya AI
+ Gundua dhana za AI inayotengeneza: 4: You
+ Chunguza jukwaa la Models la GitHub: 6: You
+ Kamilisha vigezo na maagizo ya AI: 8: You
+ section Muunganiko wa Backend
+ Jenga seva ya API ya Python: 5: You
+ Tekeleza simu za kazi za AI: 7: You
+ Shughulikia shughuli zisizo za wakati mmoja: 8: You
+ section Maendeleo ya Mbele (Frontend)
+ Tengeneza interface ya mazungumzo ya kisasa: 6: You
+ Kamilisha mwingiliano wa wakati halisi: 8: You
+ Jenga uzoefu wa mtumiaji unaojibu: 9: You
+ section Maombi ya Kitaalamu
+ Tumia mfumo kamili wa AI: 7: You
+ Boresha mifumo ya utendaji: 8: You
+ Tengeneza app inayostahili uzalishaji: 9: You
+```
+**Hatua Yako ya Mwisho**: Mwisho wa somo hili, utakuwa umejenga programu kamilifu inayotumia AI kwa kutumia teknolojia na mifumo ileile inayochochea wasaidizi wa AI wa kisasa kama ChatGPT, Claude, na Google Bard.
+
+## Kuelewa AI: Kutoka Shaka hadi Utaalamu
+
+Kabla ya kuingia kwenye msimbo, hebu kuelewa tunafanya kazi na nini. Ikiwa umewahi kutumia API hapo awali, unajua muundo wa msingi: tuma ombi, pokea jibu.
+
+API za AI hufuata muundo ule ule, lakini badala ya kupata data iliyohifadhiwa tayari kutoka kwa hifadhidata, zinatengeneza majibu mapya kulingana na mifumo iliyojifunza kutoka kwa maandishi mengi sana. Fikiria kama tofauti kati ya mfumo wa katalogi wa maktaba na mkutubi mwenye maarifa anayeweza kuchanganya taarifa kutoka vyanzo vingi.
+
+### Nini Ni "AI Inayozalisha" Kweli?
+
+Fikiria jinsi Jiwe la Rosetta lilivyoruhusu wataalamu kuelewa hieroglyphics za Misri kwa kutafuta mifumo kati ya lugha zinazoeleweka na zisizoeleweka. Mifano ya AI hufanya jambo kama hilo – huita patterns kutoka kwa maandishi mengi kuelewa jinsi lugha inavyofanya kazi, halafu hutumia mifano hiyo kutengeneza majibu yanayofaa kwa maswali mapya.
+
+**Hebu niifafanue kwa kulinganisha rahisi:**
+- **Hifadhidata ya kawaida**: Kama kuomba cheti chako cha kuzaliwa – unapata hati ile ile kila wakati
+- **Mfumo wa utafutaji**: Kama kumuomba mkutubi kupata vitabu kuhusu paka – wanaonyesha kinachopatikana
+- **AI Inayozalisha**: Kama kumuuliza rafiki mwenye maarifa kuhusu paka – wanakuambia mambo ya kuvutia kwa maneno yao wenyewe, yaliyobinafsishwa kwa kile unachotaka kujua
```mermaid
graph LR
- A[Your Question] --> B[AI Model]
- B --> C[Pattern Recognition]
- C --> D[Content Generation]
- D --> E[Contextual Response]
+ A[Swali Lako] --> B[Mfano wa AI]
+ B --> C[Utambuzi wa Mifumo]
+ C --> D[Uundaji wa Yaliyomo]
+ D --> E[Jibu la Muktadha]
- F[Training Data
Books, Articles, Web] --> B
+ F[Data ya Mafunzo
Vitabu, Makala, Tovuti] --> B
```
+### Jinsi Mifano ya AI Hujifunza (Toleo Rahisi)
-### Jinsi Miundo ya AI Inavyojifunza (Toleo Rahisi)
-
-Miundo ya AI hujifunza kupitia kufichuliwa na seti kubwa za data zinazojumuisha maandishi kutoka vitabu, makala, na mazungumzo. Kupitia mchakato huu, inatambua mifumo katika:
-- Jinsi mawazo yanavyopangwa katika mawasiliano ya maandishi
-- Maneno yanayojitokeza pamoja mara kwa mara
-- Jinsi mazungumzo yanavyotiririka kawaida
+Mifano ya AI hujifunza kupitia kufundishwa na seti kubwa za data zinazojumuisha maandishi kutoka vitabu, makala, na mazungumzo. Kupitia mchakato huu, hutambua mifumo katika:
+- Jinsi mawazo yanavyopangwa katika mawasiliano yaliyoandikwa
+- Ni maneno gani yanayotokea pamoja mara kwa mara
+- Jinsi mazungumzo huendelea kawaida
- Tofauti za muktadha kati ya mawasiliano rasmi na yasiyo rasmi
-**Ni sawa na jinsi wanajiolojia wanavyotafsiri lugha za kale**: wanachambua maelfu ya mifano ili kuelewa sarufi, msamiati, na muktadha wa kitamaduni, hatimaye kuwa na uwezo wa kutafsiri maandishi mapya kwa kutumia mifumo iliyojifunza.
+**Hii ni sawa na jinsi wanasayansi wa kale wanavyofasiri lugha za zamani**: huchambua maelfu ya mifano kuelewa sarufi, msamiati, na muktadha wa kitamaduni, na hatimaye kuwa na uwezo wa kutafsiri maandishi mapya kwa kutumia mifumo hiyo iliyojifunza.
-### Kwa Nini Miundo ya GitHub?
+### Kwa Nini GitHub Models?
-Tunatumia Miundo ya GitHub kwa sababu ya sababu ya kiutendaji – inatupa ufikiaji wa AI ya kiwango cha biashara bila kulazimika kuanzisha miundombinu yetu ya AI (ambayo, kwa hakika, hutaki kufanya sasa hivi!). Fikiria kama kutumia API ya hali ya hewa badala ya kujaribu kutabiri hali ya hewa mwenyewe kwa kuanzisha vituo vya hali ya hewa kila mahali.
+Tunatumia GitHub Models kwa sababu ya kiutendaji – inatupa upatikanaji wa AI ya viwango vya biashara bila kuanzisha miundombinu yetu ya AI (ambayo, niamini, hutaki kufanya sasa hivi!). Fikiria kama kutumia API ya hali ya hewa badala ya kujaribu kutabiri hali ya hewa mwenyewe kwa kuweka vituo vya hali ya hewa kila mahali.
-Ni kimsingi "AI-kama-Huduma," na sehemu bora? Ni bure kuanza, kwa hivyo unaweza kujaribu bila kuwa na wasiwasi kuhusu gharama kubwa.
+Hii ni "AI kama Huduma," na sehemu nzuri ni kwamba ni bure kuanza, hivyo unaweza kujaribu bila wasiwasi wa gharama kubwa.
```mermaid
graph LR
- A[Frontend Chat UI] --> B[Your Backend API]
- B --> C[GitHub Models API]
- C --> D[AI Model Processing]
+ A[UI ya Chat ya Mbele] --> B[API Yako ya Backend]
+ B --> C[API za Mfano wa GitHub]
+ C --> D[Usindikaji wa Mfano wa AI]
D --> C
C --> B
B --> A
```
+Tutatumia GitHub Models kwa muunganisho wetu wa nyuma, inayotoa upatikanaji wa uwezo wa AI wa kiwango cha kitaalamu kupitia kiolesura kinachopendelewa na waendelezaji. [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) ni mazingira ya majaribio ambapo unaweza kujaribu mifano tofauti ya AI na kuelewa uwezo wake kabla ya kuitekeleza katika msimbo.
+
+## 🧠 Mfumo wa Maendeleo ya Programu za AI
-Tutatumia Miundo ya GitHub kwa muunganisho wetu wa nyuma, ambayo hutoa ufikiaji wa uwezo wa AI wa kiwango cha kitaalamu kupitia kiolesura kinachofaa kwa watengenezaji. [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) inatumika kama mazingira ya majaribio ambapo unaweza kujaribu miundo tofauti ya AI na kuelewa uwezo wake kabla ya kuitekeleza kwenye msimbo.
+```mermaid
+mindmap
+ root((AI Development))
+ Understanding AI
+ Generative Models
+ Pattern Recognition
+ Content Generation
+ Context Understanding
+ Response Synthesis
+ AI Parameters
+ Temperature Control
+ Token Limits
+ Top-p Filtering
+ System Prompts
+ Backend Architecture
+ API Integration
+ GitHub Models
+ Authentication
+ Request Handling
+ Error Management
+ Python Infrastructure
+ FastAPI Framework
+ Async Operations
+ Environment Security
+ CORS Configuration
+ Frontend Experience
+ Chat Interface
+ Real-time Updates
+ Message History
+ User Feedback
+ Loading States
+ Modern Web Tech
+ ES6 Classes
+ Async/Await
+ DOM Manipulation
+ Event Handling
+ Professional Patterns
+ Security Best Practices
+ Token Management
+ Input Validation
+ XSS Prevention
+ Error Boundaries
+ Production Readiness
+ Performance Optimization
+ Responsive Design
+ Accessibility
+ Testing Strategies
+```
+**Kanuni Msingi**: Maendeleo ya programu za AI yanachanganya ujuzi wa maendeleo ya wavuti wa kawaida na muunganisho wa huduma za AI, kuunda programu za akili zinazohisi kuwa za asili na zinazojibu watumiaji vizuri.
-
+
-**Hivi ndivyo uwanja wa majaribio unavyofaa:**
-- **Jaribu** miundo tofauti ya AI kama GPT-4o-mini, Claude, na nyinginezo (bure kabisa!)
-- **Pima** mawazo yako na maelekezo kabla ya kuandika msimbo wowote
-- **Pata** vipande vya msimbo vilivyotayarishwa kwa lugha yako ya programu unayoipenda
-- **Rekebisha** mipangilio kama kiwango cha ubunifu na urefu wa majibu ili kuona jinsi yanavyoathiri matokeo
+**Hapa ni kinachofanya playground kuwa muhimu:**
+- **Jaribu** mifano tofauti ya AI kama GPT-4o-mini, Claude, na mingine (zote ni bure!)
+- **Testi** mawazo yako na maelekezo kabla hujaandika msimbo wowote
+- **Pata** vipande vya msimbo vinavyotumika moja kwa moja kwa lugha unayopendelea ya programu
+- **Boresha** mipangilio kama kiwango cha ubunifu na urefu wa jibu kuona jinsi zinavyoathiri matokeo
-Baada ya kucheza kidogo, bonyeza tu kichupo cha "Code" na uchague lugha yako ya programu ili kupata msimbo wa utekelezaji utakaohitaji.
+Baada ya kucheza kidogo, bonyeza kichupo cha "Code" na chagua lugha yako ya programu kupata msimbo wa utekelezaji utakao hitajiwa.
-
+
-## Kuweka Muunganisho wa Nyuma wa Python
+## Kuanzisha Muunganisho wa Backend wa Python
-Sasa hebu tutekeleze muunganisho wa AI kwa kutumia Python. Python ni bora kwa programu za AI kwa sababu ya sintaksia yake rahisi na maktaba zenye nguvu. Tutaanza na msimbo kutoka uwanja wa majaribio wa Miundo ya GitHub kisha kuubadilisha kuwa kazi inayoweza kutumika tena na inayofaa kwa uzalishaji.
+Sasa tutaweka muunganisho wa AI kwa kutumia Python. Python ni nzuri kwa programu za AI kwa sababu ya sarufi yake rahisi na maktaba zenye nguvu. Tutaanza na msimbo kutoka GitHub Models playground kisha tuurekebishe ili kuwa kazi inayoweza kutumika tena na tayari kwa uzalishaji.
### Kuelewa Utekelezaji wa Msingi
-Unapochukua msimbo wa Python kutoka uwanja wa majaribio, utapata kitu kinachoonekana kama hiki. Usijali ikiwa inaonekana kuwa nyingi mwanzoni – hebu tuipitie kipande kwa kipande:
+Unapopata msimbo wa Python kutoka playground, utapata kitu kinachofanana na hiki. Usijali kama kinaonekana kuwa kingi mwanzoni – tuitakaye kidogo kidogo:
```python
"""Run this model in Python
@@ -106,14 +217,13 @@ Unapochukua msimbo wa Python kutoka uwanja wa majaribio, utapata kitu kinachoone
import os
from openai import OpenAI
-# To authenticate with the model you will need to generate a personal access token (PAT) in your GitHub settings.
-# Create your PAT token by following instructions here: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
+# Ili kuthibitisha na modeli utahitaji kuunda tokeni ya upatikanaji binafsi (PAT) kwenye mipangilio yako ya GitHub.
+# Unda tokeni yako ya PAT kwa kufuata maelekezo hapa: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
client = OpenAI(
base_url="https://models.github.ai/inference",
api_key=os.environ["GITHUB_TOKEN"],
)
-```python
response = client.chat.completions.create(
messages=[
{
@@ -134,17 +244,17 @@ response = client.chat.completions.create(
print(response.choices[0].message.content)
```
-**Hivi ndivyo kinachotokea kwenye msimbo huu:**
-- **Tunajumuisha** zana tunazohitaji: `os` kwa kusoma vigezo vya mazingira na `OpenAI` kwa kuzungumza na AI
-- **Tunasanidi** mteja wa OpenAI kuelekeza kwenye seva za AI za GitHub badala ya OpenAI moja kwa moja
-- **Tunathibitisha** kwa kutumia tokeni maalum ya GitHub (zaidi kuhusu hilo baadaye!)
-- **Tunapanga** mazungumzo yetu na "roles" tofauti – fikiria kama kuweka mandhari ya mchezo wa kuigiza
-- **Tunatuma** ombi letu kwa AI na baadhi ya vigezo vya kurekebisha
-- **Tunatoa** maandishi halisi ya majibu kutoka kwa data yote inayorudi
+**Hivi ndivyo msimbo unavyofanya:**
+- **Tunachukua** zana tunazohitaji: `os` kusoma mazingira ya mabadiliko na `OpenAI` kuzungumza na AI
+- **Tunaanzisha** mteja wa OpenAI kuelekea seva za AI za GitHub badala ya OpenAI moja kwa moja
+- **Tunathibitisha** kwa kutumia tokeni maalum ya GitHub (zaidi kuhusu hayo baadae!)
+- **Tunapanga** mazungumzo yetu na "maudhi" tofauti – fikiria kama kuweka onyesho kwa tamthilia
+- **Tunatuma** ombi letu kwa AI na baadhi ya vigezo vya kufinyanga
+- **Tunachukua** maandishi halisi ya jibu kutoka kwenye data yote inayorudi
-### Kuelewa Majukumu ya Ujumbe: Mfumo wa Mazungumzo ya AI
+### Kuelewa Nafasi za Ujumbe: Mfumo wa Mazungumzo wa AI
-Mazungumzo ya AI hutumia muundo maalum na "roles" tofauti zinazotumikia madhumuni maalum:
+Mazungumzo ya AI hutumia muundo maalum wenye “maudhi” tofauti yenye majukumu tofauti:
```python
messages=[
@@ -159,97 +269,97 @@ messages=[
]
```
-**Fikiria kama kuongoza mchezo wa kuigiza:**
-- **System role**: Kama maelekezo ya jukwaa kwa mwigizaji – inamwambia AI jinsi ya kujiendesha, tabia gani kuwa nayo, na jinsi ya kujibu
-- **User role**: Swali halisi au ujumbe kutoka kwa mtu anayetumia programu yako
-- **Assistant role**: Jibu la AI (hili hutumika katika historia ya mazungumzo lakini halitumwi)
+**Fikiria kama kuongoza tamthilia:**
+- **Nafasi ya mfumo**: Kama maelekezo ya jukwaani kwa mhusika – inamuambia AI jinsi ya tabia, utu wake, na jinsi ya kujibu
+- **Nafasi ya mtumiaji**: Swali halisi au ujumbe kutoka kwa mtu anayetumia programu yako
+- **Nafasi ya msaidizi**: Jibu la AI (huli tuma, lakini linaonekana katika historia ya mazungumzo)
-**Mfano wa maisha halisi**: Fikiria unamtambulisha rafiki kwa mtu kwenye sherehe:
-- **Ujumbe wa mfumo**: "Huyu ni rafiki yangu Sarah, yeye ni daktari mzuri katika kuelezea dhana za matibabu kwa njia rahisi"
-- **Ujumbe wa mtumiaji**: "Unaweza kuelezea jinsi chanjo zinavyofanya kazi?"
-- **Jibu la msaidizi**: Sarah anajibu kama daktari rafiki, si kama wakili au mpishi
+**Mfano wa maisha halisi**: Fikiria unamtambulisha rafiki kwa mtu kwenye karamu:
+- **Ujumbe wa mfumo**: "Huyu ni rafiki yangu Sarah, ni daktari mzuri wa kuelezea dhana za matibabu kwa maneno rahisi"
+- **Ujumbe wa mtumiaji**: "Unaweza kufafanua jinsi chanjo zinavyofanya kazi?"
+- **Jibu la msaidizi**: Sarah anajibu kama daktari mkarimu, si kama mwanasheria au mpishi
-### Kuelewa Vigezo vya AI: Kurekebisha Tabia ya Majibu
+### Kuelewa Vigezo vya AI: Kufinyanga Tabia ya Jibu
-Vigezo vya nambari katika miito ya API ya AI vinadhibiti jinsi modeli inavyotoa majibu. Mipangilio hii inakuruhusu kurekebisha tabia ya AI kwa matumizi tofauti:
+Vigezo vya nambari katika API za AI vinadhibiti jinsi mfano unavyotengeneza majibu. Mipangilio hii inakuwezesha kurekebisha tabia ya AI kwa matumizi tofauti:
-#### Temperature (0.0 hadi 2.0): Kidhibiti Ubunifu
+#### Joto (0.0 hadi 2.0): Diali ya Ubunifu
-**Kazi yake**: Hudhibiti jinsi majibu ya AI yatakavyokuwa ya ubunifu au yanayotarajiwa.
+**Inafanya nini**: Inadhibiti ni kiasi gani majibu ya AI yatakuwa ya ubunifu au yanayoweza kutabirika.
-**Fikiria kama kiwango cha ubunifu cha mpiga jazz:**
-- **Temperature = 0.1**: Kucheza melodi ile ile kila wakati (inayotarajiwa sana)
-- **Temperature = 0.7**: Kuongeza tofauti za ladha huku ikibaki kutambulika (ubunifu wa wastani)
-- **Temperature = 1.5**: Jazz ya majaribio kamili na mabadiliko yasiyotarajiwa (isiyotabirika sana)
+**Fikiria kama kiwango cha kuigiza kwa mwanamuziki wa jazz:**
+- **Joto = 0.1**: Kuimba melodi ile ile kila mara (inayoweza kutabirika sana)
+- **Joto = 0.7**: Kuongeza mabadiliko ya ladha huku ukibaki waeleweke (uwezo wa ubunifu wa wastani)
+- **Joto = 1.5**: Jazz ya majaribio kamili yenye miondoko isiyotabirika (ubunifu mkubwa)
```python
-# Very predictable responses (good for factual questions)
+# Majibu yanayoweza kutabirika sana (mzuri kwa maswali ya ukweli)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "What is 2+2?"}],
- temperature=0.1 # Will almost always say "4"
+ temperature=0.1 # Takriban kila mara atasema "4"
)
-# Creative responses (good for brainstorming)
+# Majibu ya ubunifu (mzuri kwa kuibua mawazo)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Write a creative story opening"}],
- temperature=1.2 # Will generate unique, unexpected stories
+ temperature=1.2 # Atatengeneza hadithi za kipekee, zisizotarajiwa
)
```
-#### Max Tokens (1 hadi 4096+): Kidhibiti Urefu wa Majibu
+#### Juu ya Tokens (1 hadi 4096+): Kidhibiti cha Urefu wa Jibu
-**Kazi yake**: Huweka kikomo cha jinsi majibu ya AI yanavyoweza kuwa marefu.
+**Inafanya nini**: Inaweka kikomo juu ya urefu wa jibu la AI.
-**Fikiria tokeni kama maneno kwa takriban** (karibu tokeni 1 = maneno 0.75 kwa Kiingereza):
-- **max_tokens=50**: Fupi na tamu (kama ujumbe wa maandishi)
-- **max_tokens=500**: Aya moja au mbili nzuri
-- **max_tokens=2000**: Maelezo ya kina na mifano
+**Fikiria tokens kama maneno kwa takriban** (kati ya token moja = karibu maneno 0.75 kwa Kiingereza):
+- **max_tokens=50**: Fupi na tamu (kama ujumbe mfupi)
+- **max_tokens=500**: Aya nzuri au mbili
+- **max_tokens=2000**: Maelezo ya kina yenye mifano
```python
-# Short, concise answers
+# Majibu mafupi na ya wazi
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
- max_tokens=100 # Forces a brief explanation
+ max_tokens=100 # Inalazimisha maelezo mafupi
)
-# Detailed, comprehensive answers
+# Majibu ya kina na ya kina
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
- max_tokens=1500 # Allows for detailed explanations with examples
+ max_tokens=1500 # Inaruhusu maelezo ya kina pamoja na mifano
)
```
-#### Top_p (0.0 hadi 1.0): Kidhibiti Umakini
+#### Top_p (0.0 hadi 1.0): Kigezo cha Kuzingatia
-**Kazi yake**: Hudhibiti jinsi AI inavyobaki makini kwenye majibu yanayowezekana zaidi.
+**Inafanya nini**: Inadhibiti jinsi AI inavyolingania na majibu yanayoweza kutokea zaidi.
-**Fikiria AI kuwa na msamiati mkubwa, uliopangwa kulingana na uwezekano wa kila neno:**
-- **top_p=0.1**: Inazingatia maneno 10% ya juu zaidi yanayowezekana (makini sana)
-- **top_p=0.9**: Inazingatia 90% ya maneno yanayowezekana (ubunifu zaidi)
-- **top_p=1.0**: Inazingatia kila kitu (tofauti kubwa)
+**Picha inaonyesha AI akiwa na msamiati mkubwa, umesawazishwa kwa uwezekano wa kila neno:**
+- **top_p=0.1**: Inazingatia maneno 10% ya juu yenye uwezekano mkubwa zaidi (ilenye makini sana)
+- **top_p=0.9**: Inazingatia 90% ya maneno yanayowezekana (zaidi ya ubunifu)
+- **top_p=1.0**: Inazingatia yote (tofauti kubwa zaidi)
-**Kwa mfano**: Ukisema "Anga kwa kawaida ni..."
-- **Top_p ya chini**: Karibu hakika itasema "bluu"
-- **Top_p ya juu**: Inaweza kusema "bluu", "mawingu", "kubwa", "inabadilika", "nzuri", n.k.
+**Kwa mfano**: Ukiuliza "Anga ni kawaida..."
+- **Top_p ya chini**: Kusema "buluu" kabisa bila shaka
+- **Top_p ya juu**: Inaweza kusema "buluu", "mawingu", "kubwa", "kubadilika", "mzuri", n.k.
-### Kuweka Yote Pamoja: Mchanganyiko wa Vigezo kwa Matumizi Tofauti
+### Kuunganisha Pamoja: Mchanganyiko wa Vigezo kwa Matumizi Tofauti
```python
-# For factual, consistent answers (like a documentation bot)
+# Kwa majibu ya kweli, ya kuzingatia (kama roboti wa hati)
factual_params = {
"temperature": 0.2,
"max_tokens": 300,
"top_p": 0.3
}
-# For creative writing assistance
+# Kwa msaada wa uandishi wa ubunifu
creative_params = {
"temperature": 1.1,
"max_tokens": 1000,
"top_p": 0.9
}
-# For conversational, helpful responses (balanced)
+# Kwa majibu ya mazungumzo, yenye msaada (yenye uwiano)
conversational_params = {
"temperature": 0.7,
"max_tokens": 500,
@@ -257,56 +367,293 @@ conversational_params = {
}
```
-**Kuelewa kwa nini vigezo hivi ni muhimu**: Programu tofauti zinahitaji aina tofauti za majibu. Boti ya huduma kwa wateja inapaswa kuwa thabiti na ya ukweli (temperature ya chini), wakati msaidizi wa uandishi wa ubunifu anapaswa kuwa wa kufikiria na wa tofauti (temperature ya juu). Kuelewa vigezo hivi kunakupa udhibiti wa tabia na mtindo wa majibu ya AI yako.
-**Hii ndiyo sababu FastAPI ni bora kwa kile tunachojenga:**
-- **Async kwa default**: Inaweza kushughulikia maombi mengi ya AI kwa wakati mmoja bila kukwama
-- **Nyaraka za kiotomatiki**: Tembelea `/docs` na upate ukurasa mzuri wa nyaraka za API unaoweza kuingiliana bila malipo
-- **Uthibitishaji wa ndani**: Hukamata makosa kabla hayajasababisha matatizo
-- **Haraka sana**: Mojawapo ya mifumo ya Python yenye kasi zaidi
-- **Python ya kisasa**: Inatumia vipengele vyote vya hivi karibuni na bora vya Python
+```mermaid
+quadrantChart
+ title Mkataba wa Uboreshaji wa Vigezo vya AI
+ x-axis Ubunifu Mdogo --> Ubunifu Mkubwa
+ y-axis Jibu Fupi --> Jibu Refu
+
+ quadrant-1 Maudhui ya Ubunifu
+ quadrant-2 Uchambuzi wa Kina
+ quadrant-3 Taarifa za Haraka
+ quadrant-4 AI ya Mazungumzo
+
+ Documentation Bot: [0.2, 0.3]
+ Customer Service: [0.4, 0.4]
+ General Assistant: [0.7, 0.5]
+ Creative Writer: [0.9, 0.9]
+ Brainstorming Tool: [0.8, 0.8]
+```
+**Kuelewa kwa nini vigezo hivi ni muhimu**: Programu tofauti zinahitaji aina tofauti za majibu. Bot wa huduma kwa wateja anatakiwa kuwa thabiti na wa ukweli (joto la chini), wakati msaidizi wa uandishi wa ubunifu anatakiwa kuwa wa mawazo na mabadiliko (joto la juu). Kuelewa vigezo hivi kunakupa udhibiti juu ya utu na mtindo wa jibu wa AI yako.
+```
+
+**Here's what's happening in this code:**
+- **We import** the tools we need: `os` for reading environment variables and `OpenAI` for talking to the AI
+- **We set up** the OpenAI client to point to GitHub's AI servers instead of OpenAI directly
+- **We authenticate** using a special GitHub token (more on that in a minute!)
+- **We structure** our conversation with different "roles" – think of it like setting the scene for a play
+- **We send** our request to the AI with some fine-tuning parameters
+- **We extract** the actual response text from all the data that comes back
+
+> 🔐 **Security Note**: Never hardcode API keys in your source code! Always use environment variables to store sensitive credentials like your `GITHUB_TOKEN`.
+
+### Creating a Reusable AI Function
+
+Let's refactor this code into a clean, reusable function that we can easily integrate into our web application:
+
+```python
+import asyncio
+from openai import AsyncOpenAI
+
+# Use AsyncOpenAI for better performance
+client = AsyncOpenAI(
+ base_url="https://models.github.ai/inference",
+ api_key=os.environ["GITHUB_TOKEN"],
+)
+
+async def call_llm_async(prompt: str, system_message: str = "You are a helpful assistant."):
+ """
+ Sends a prompt to the AI model asynchronously and returns the response.
+
+ Args:
+ prompt: The user's question or message
+ system_message: Instructions that define the AI's behavior and personality
+
+ Returns:
+ str: The AI's response to the prompt
+ """
+ try:
+ response = await client.chat.completions.create(
+ messages=[
+ {
+ "role": "system",
+ "content": system_message,
+ },
+ {
+ "role": "user",
+ "content": prompt,
+ }
+ ],
+ model="openai/gpt-4o-mini",
+ temperature=1,
+ max_tokens=4096,
+ top_p=1
+ )
+ return response.choices[0].message.content
+ except Exception as e:
+ logger.error(f"AI API error: {str(e)}")
+ return "I'm sorry, I'm having trouble processing your request right now."
+
+# Backward compatibility function for synchronous calls
+def call_llm(prompt: str, system_message: str = "You are a helpful assistant."):
+ """Synchronous wrapper for async AI calls."""
+ return asyncio.run(call_llm_async(prompt, system_message))
+```
+
+**Kuelewa kazi hii iliyoboreshwa:**
+- **Inakubali** vigezo viwili: maelekezo ya mtumiaji na ujumbe wa mfumo wa hiari
+- **Inatoa** ujumbe wa mfumo wa msingi kwa tabia ya msaidizi kwa ujumla
+- **Inatumia** aina za Python kwa usahihi kwa ajili ya nyaraka bora za msimbo
+- **Inajumuisha** maelezo ya kina ya kazi na vigezo vyake
+- **Inarejesha** maudhui ya jibu tu, kufanya iwe rahisi kutumia katika API yetu ya wavuti
+- **Inadumisha** vigezo vile vile vya mfano kwa tabia thabiti ya AI
+
+### Uchawi wa Maelekezo ya Mfumo: Kuprogramu Utu wa AI
+
+Ikiwa vigezo vinadhibiti jinsi AI inavyofikiria, maelekezo ya mfumo yanadhibiti ni nani AI anayejiamini kuwa. Hii ni mojawapo ya sehemu za kuvutia zaidi za kufanya kazi na AI – unampa AI utu kamili, kiwango cha utaalamu, na mtindo wa mawasiliano.
+
+**Fikiria maelekezo ya mfumo kama kung'oa wauigizaji tofauti kwa majukumu tofauti**: Badala ya kuwa na msaidizi mmoja wa kawaida, unaweza kuunda wataalamu maalum kwa hali tofauti. Unahitaji mwalimu mvumilivu? Mshirika wa ubunifu? Mshauri wa biashara asiye na upotovu? Badilisha tu maelekezo ya mfumo!
+
+#### Kwa Nini Maelekezo ya Mfumo Ni Yenye Nguvu
+
+Sehemu ya kuvutia: mifano ya AI imetengenezwa kwa mazungumzo mengi ambapo watu hukumbatia majukumu na viwango vya utaalamu tofauti. Unapompa AI jukumu maalum, ni kama kuwasha swichi inayochochea mifumo yote hiyo iliyojifunza.
+
+**Ni kama utendaji wa kina kwa AI**: Mwambie mwigizaji "wewe ni profesa mzee mwenye busara" na uone jinsi wanavyobadilisha mkao, msamiati, na tabia zao. AI hufanya kitu kinachofanana sana na mifumo ya lugha.
+
+#### Kuunda Maelekezo Bora ya Mfumo: Sanaa na Sayansi
+
+**Muundo wa maelekezo bora ya mfumo:**
+1. **Jukumu/Utu**: AI ni nani?
+2. **Utaalamu**: Anajua nini?
+3. **Mtindo wa mawasiliano**: Anazungumza vipi?
+4. **Maelekezo maalum**: Angalau atazingatia nini?
+
+```python
+# ❌ Amri ya mfumo isiyoeleweka
+"You are helpful."
+
+# ✅ Amri ya mfumo yenye maelezo, yenye ufanisi
+"You are Dr. Sarah Chen, a senior software engineer with 15 years of experience at major tech companies. You explain programming concepts using real-world analogies and always provide practical examples. You're patient with beginners and enthusiastic about helping them understand complex topics."
+```
+
+#### Mifano ya Maelekezo ya Mfumo kwa Muktadha
+
+Tuwone jinsi maelekezo tofauti ya mfumo yanavyounda utu tofauti kabisa wa AI:
+
+```python
+# Mfano 1: Mwalimu Muvumilivu
+teacher_prompt = """
+You are an experienced programming instructor who has taught thousands of students.
+You break down complex concepts into simple steps, use analogies from everyday life,
+and always check if the student understands before moving on. You're encouraging
+and never make students feel bad for not knowing something.
+"""
+
+# Mfano 2: Mshirikishi Mbunifu
+creative_prompt = """
+You are a creative writing partner who loves brainstorming wild ideas. You're
+enthusiastic, imaginative, and always build on the user's ideas rather than
+replacing them. You ask thought-provoking questions to spark creativity and
+offer unexpected perspectives that make stories more interesting.
+"""
+
+# Mfano 3: Mshauri Mkakati wa Biashara
+business_prompt = """
+You are a strategic business consultant with an MBA and 20 years of experience
+helping startups scale. You think in frameworks, provide structured advice,
+and always consider both short-term tactics and long-term strategy. You ask
+probing questions to understand the full business context before giving advice.
+"""
+```
+
+#### Kuona Maelekezo ya Mfumo Kazi
+
+Tujaribu swali lile lile na maelekezo tofauti ya mfumo kuona tofauti kubwa:
+
+**Swali**: "Ninawezaje kushughulikia uthibitishaji wa mtumiaji katika app yangu ya wavuti?"
+
+```python
+# Kwa maelekezo ya mwalimu:
+teacher_response = call_llm(
+ "How do I handle user authentication in my web app?",
+ teacher_prompt
+)
+# Jibu la kawaida: "Swali zuri! Hebu tugawanye uthibitishaji katika hatua rahisi.
+# Fikiria kama mlinzi wa klabu ya usiku anayeangalia kitambulisho..."
+
+# Kwa maelekezo ya biashara:
+business_response = call_llm(
+ "How do I handle user authentication in my web app?",
+ business_prompt
+)
+# Jibu la kawaida: "Kwa mtazamo wa kimkakati, uthibitishaji ni muhimu kwa
+# imani ya mtumiaji na uzingatiaji wa sheria. Acha nitoe muundo ukizingatia usalama,
+# uzoefu wa mtumiaji, na uwezekano wa kupanuka..."
+```
+
+#### Mbinu Zinazopiga Kufika za Maelekezo ya Mfumo
+
+**1. Kuweka Muktadha**: Mpa AI taarifa za awali
+```python
+system_prompt = """
+You are helping a junior developer who just started their first job at a startup.
+They know basic HTML/CSS/JavaScript but are new to backend development and databases.
+Be encouraging and explain things step-by-step without being condescending.
+"""
+```
+
+**2. Kupangilia Matokeo**: Mwambie AI jinsi ya kupanga majibu
+```python
+system_prompt = """
+You are a technical mentor. Always structure your responses as:
+1. Quick Answer (1-2 sentences)
+2. Detailed Explanation
+3. Code Example
+4. Common Pitfalls to Avoid
+5. Next Steps for Learning
+"""
+```
+
+**3. Kuweka Vizingiti**: Eleza kile ambacho AI haipaswi kufanya
+```python
+system_prompt = """
+You are a coding tutor focused on teaching best practices. Never write complete
+solutions for the user - instead, guide them with hints and questions so they
+learn by doing. Always explain the 'why' behind coding decisions.
+"""
+```
+
+#### Kwa Nini Hii Inahusu Msaidizi Wako wa Chat
+
+Kuelewa maelekezo ya mfumo kunakupa nguvu kubwa ya kuunda wasaidizi maalum wa AI:
+- **Bot ya huduma kwa wateja**: Msaidizi, mvumilivu, anayejuwa sera
+- **Mwalimu wa kujifunza**: Anayehimiza, hatua kwa hatua, anathibitisha kuelewa
+- **Mshirika mbunifu**: Mzuri katika kufikiria, huongeza mawazo, huuliza "je, vipi?"
+- **Mtaalamu wa kiufundi**: Sahihi, ana maelezo, anayeangalia usalama
+
+**Mwelekeo muhimu**: Haujui tu kuwaita API ya AI – unaunda utu maalum wa AI unaotumikia matumizi yako maalum. Hii ndiyo inayofanya programu za kisasa za AI kuonekana zimebinafsishwa na zikiwa na manufaa badala ya za kawaida.
+
+### 🎯 Ukaguzi wa Kitaalamu: Kuprogramu Utu wa AI
+
+**Acha na Fikiria**: Umejifunza programu za utu wa AI kupitia maelekezo ya mfumo. Hii ni ujuzi wa msingi katika maendeleo ya programu za kisasa za AI.
-**Na hii ndiyo sababu tunahitaji backend kabisa:**
+**Tathmini Haraka ya Kibinafsi**:
+- Je, unaweza kueleza tofauti kati ya maelekezo ya mfumo na ujumbe wa kawaida wa mtumiaji?
+- Je, tofauti kati ya vigezo vya joto na top_p ni ipi?
+- Je, ungeundaje maelekezo ya mfumo kwa matumizi maalum (kama mwalimu wa kupanga programu)?
-**Usalama**: API key yako ya AI ni kama nywila – ukiiweka kwenye JavaScript ya frontend, mtu yeyote anayepitia msimbo wa tovuti yako anaweza kuiba na kutumia mikopo yako ya AI. Backend inahifadhi hati nyeti salama.
+**Uhusiano wa Dunia halisi**: Mbinu za maelekezo ya mfumo ulizojifunza hutumika katika kila programu kuu ya AI - kuanzia msaada wa uandishi wa GitHub Copilot hadi kiolesura cha mazungumzo cha ChatGPT. Unatambua mifumo ile ile inayotumiwa na timu za bidhaa za AI katika makampuni makubwa ya teknolojia.
-**Kudhibiti Kiwango cha Maombi**: Backend inakuruhusu kudhibiti mara ngapi watumiaji wanaweza kufanya maombi, kutekeleza uthibitishaji wa watumiaji, na kuongeza ufuatiliaji wa matumizi.
+**Swali la Changamoto**: Unawezaje kubuni utu tofauti wa AI kwa aina tofauti za watumiaji (mwanzo dhidi ya mtaalamu)? Fikiria jinsi mfano huo huo wa AI unavyoweza kuhudumia hadhira tofauti kupitia uhandisi wa maelekezo.
-**Usindikaji wa Data**: Unaweza kutaka kuhifadhi mazungumzo, kuchuja maudhui yasiyofaa, au kuunganisha huduma nyingi za AI. Backend ndiyo mahali mantiki hii inapoishi.
+## Kujenga Web API kwa FastAPI: Kituo chako cha Mawasiliano ya AI ya Ufanisi Mno
-**Muundo unafanana na mfano wa mteja-server:**
-- **Frontend**: Safu ya kiolesura cha mtumiaji kwa mwingiliano
-- **Backend API**: Safu ya usindikaji wa maombi na uelekezaji
-- **Huduma ya AI**: Hesabu ya nje na kizazi cha majibu
-- **Vigezo vya Mazingira**: Usanidi salama na uhifadhi wa hati
+Sasa tuanze kujenga backend inayounganisha frontend yako na huduma za AI. Tutatumia FastAPI, fremu ya kisasa ya Python inayobobea katika ujenzi wa API za programu za AI.
-### Kuelewa Mtiririko wa Maombi na Majibu
+FastAPI inatoa faida kadhaa kwa mradi huu: msaada wa async ukiwezesha kushughulikia maombi mengi sambamba, utengenezaji wa moja kwa moja wa nyaraka za API, na utendaji bora. Server yako ya FastAPI inafanya kazi kama mpatanishi anayepokea maombi kutoka frontend, kuwasiliana na huduma za AI, na kurudisha majibu yaliyopangwa.
-Hebu tufuate kinachotokea mtumiaji anapotuma ujumbe:
+### Kwa Nini FastAPI Kwa Programu za AI?
+
+Huenda unajiuliza: "Siwezi tu kuitwa AI moja kwa moja kutoka JavaScript ya frontend yangu?" au "Kwa nini FastAPI badala ya Flask au Django?" Maswali mazuri!
+
+**Hapa ndio sababu FastAPI ni bora kwa tunachojenga:**
+- **Async kwa default**: Inaweza kushughulikia maombi mengi ya AI kwa wakati mmoja bila kuziba
+- **Nyaraka moja kwa moja**: Tembelea `/docs` upate ukurasa mzuri wa nyaraka za API zenye mwingiliano bure
+- **Uthibitishaji uliojengewa ndani**: Hugundua makosa kabla hayajasababisha matatizo
+- **Haraka sana**: Moja ya fremu za Python zenye kasi zaidi
+- **Python ya kisasa**: Inatumia vipengele vyote vya hivi karibuni vya Python
+
+**Na hapa ndio kwanini tunahitaji backend kabisa:**
+
+**Usalama**: Ufunguo wako wa API ya AI ni kama nenosiri – ukiuweka kwenye JavaScript ya frontend, mtu yeyote anayehakikisha chanzo cha tovuti yako anaweza kuiba na kutumia mikopo yako ya AI. Backend huhifadhi habari nyeti salama.
+
+**Kudhibiti Kasi na Udhibiti**: Backend inakusaidia kudhibiti mara ngapi watumiaji wanaweza kutuma maombi, kutekeleza uthibitishaji wa watumiaji, na kuongeza rejista ya matumizi.
+
+**Usindikaji Data**: Huenda unataka kuhifadhi mazungumzo, kuchuja maudhui yasiyofaa, au kuunganisha huduma nyingi za AI. Backend ndio mahali hii mantiki inakuwa.
+
+**Muundo unafanana na mfano wa mteja-serveri:**
+- **Frontend**: Tabaka la kiolesura cha mtumiaji kwa mwingiliano
+- **Backend API**: Tabaka la usindikaji wa maombi na kupitisha
+- **Huduma ya AI**: Utambuzi wa nje na uzalishaji wa majibu
+- **Mabadiliko ya Mazingira**: Usanidi salama na uhifadhi wa nyaraka za siri
+
+### Kuelewa Mtiririko wa Ombi-Jibu
+
+Tufuate kinachoendelea wakati mtumiaji anapotuma ujumbe:
```mermaid
sequenceDiagram
- participant User as 👤 User
- participant Frontend as 🌐 Frontend
- participant API as 🔧 FastAPI Server
- participant AI as 🤖 AI Service
+ participant User as 👤 Mtumiaji
+ participant Frontend as 🌐 Mbele ya Mbele
+ participant API as 🔧 Seva ya FastAPI
+ participant AI as 🤖 Huduma ya AI
- User->>Frontend: Types "Hello AI!"
+ User->>Frontend: Andika "Hello AI!"
Frontend->>API: POST /hello {"message": "Hello AI!"}
- Note over API: Validates request
Adds system prompt
- API->>AI: Sends formatted request
- AI->>API: Returns AI response
- Note over API: Processes response
Logs conversation
- API->>Frontend: {"response": "Hello! How can I help?"}
- Frontend->>User: Displays AI message
+ Note over API: Inathibitisha ombi
Inaongeza kiito mfumo
+ API->>AI: Inatuma ombi lililopangwa
+ AI->>API: Inarudisha jibu la AI
+ Note over API: Inachakata jibu
Inaandika mazungumzo
+ API->>Frontend: {"response": "Hello! Naweza kusaidia vipi?"}
+ Frontend->>User: Inaonyesha ujumbe wa AI
```
-
**Kuelewa kila hatua:**
-1. **Mwingiliano wa mtumiaji**: Mtu anaandika kwenye kiolesura cha mazungumzo
-2. **Usindikaji wa frontend**: JavaScript inakamata pembejeo na kuunda kama JSON
-3. **Uthibitishaji wa API**: FastAPI inathibitisha kiotomatiki ombi kwa kutumia mifano ya Pydantic
-4. **Muunganisho wa AI**: Backend inaongeza muktadha (mfano wa mfumo) na kuita huduma ya AI
-5. **Usimamizi wa majibu**: API inapokea majibu ya AI na inaweza kuyabadilisha ikiwa inahitajika
-6. **Onyesho la frontend**: JavaScript inaonyesha majibu kwenye kiolesura cha mazungumzo
+1. **Mwingiliano wa mtumiaji**: Mtu anaandika katika kiolesura cha mazungumzo
+2. **Usindikaji wa frontend**: JavaScript inachukua maingizo na kuyaweka katika muundo wa JSON
+3. **Uthibitishaji wa API**: FastAPI inathibitisha maombi moja kwa moja kwa kutumia mifano ya Pydantic
+4. **Uingizaji wa AI**: Backend inaongeza muktadha (maelekezo ya mfumo) na kuita huduma ya AI
+5. **Ushughulikiaji wa jibu**: API inapokea jibu la AI na inaweza kulibadilisha kama ni lazima
+6. **Onyesho la frontend**: JavaScript inaonyesha jibu kwenye kiolesura cha mazungumzo
### Kuelewa Muundo wa API
@@ -317,17 +664,38 @@ sequenceDiagram
participant AI Function
participant GitHub Models
- Frontend->>FastAPI: POST /hello {"message": "Hello AI!"}
+ Frontend->>FastAPI: POST /hello {"message": "Hujambo AI!"}
FastAPI->>AI Function: call_llm(message, system_prompt)
- AI Function->>GitHub Models: API request
- GitHub Models->>AI Function: AI response
- AI Function->>FastAPI: response text
- FastAPI->>Frontend: {"response": "Hello! How can I help?"}
+ AI Function->>GitHub Models: Ombi la API
+ GitHub Models->>AI Function: Jibu la AI
+ AI Function->>FastAPI: maandishi ya jibu
+ FastAPI->>Frontend: {"response": "Hujambo! Naweza kusaidia vipi?"}
+```
+```mermaid
+flowchart TD
+ A[Ingizo la Mtumiaji] --> B[Uthibitishaji wa Mbele]
+ B --> C[Ombi la HTTP POST]
+ C --> D[Router ya FastAPI]
+ D --> E[Uthibitishaji wa Pydantic]
+ E --> F[Simu ya Kazi ya AI]
+ F --> G[API za Modeli za GitHub]
+ G --> H[Usindikaji wa Majibu]
+ H --> I[Jibu la JSON]
+ I --> J[Usasishaji wa Mbele]
+
+ subgraph "Tabaka la Usalama"
+ K[Kati ya CORS]
+ L[Hali za Mazingira]
+ M[Ushughulikiaji wa Makosa]
+ end
+
+ D --> K
+ F --> L
+ H --> M
```
-
### Kuunda Programu ya FastAPI
-Hebu tujenge API yetu hatua kwa hatua. Unda faili inayoitwa `api.py` na msimbo wa FastAPI ufuatao:
+Tujenge API yetu hatua kwa hatua. Tengeneza faili liitwalo `api.py` na msimbo unaofuata wa FastAPI:
```python
# api.py
@@ -337,27 +705,27 @@ from pydantic import BaseModel
from llm import call_llm
import logging
-# Configure logging
+# Sanidi uandikishaji logi
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
-# Create FastAPI application
+# Unda programu ya FastAPI
app = FastAPI(
title="AI Chat API",
description="A high-performance API for AI-powered chat applications",
version="1.0.0"
)
-# Configure CORS
+# Sanidi CORS
app.add_middleware(
CORSMiddleware,
- allow_origins=["*"], # Configure appropriately for production
+ allow_origins=["*"], # Sanidi ipasavyo kwa ajili ya uzalishaji
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
-# Pydantic models for request/response validation
+# Mifano ya Pydantic kwa uthibitishaji wa ombi/jibu
class ChatMessage(BaseModel):
message: str
@@ -382,14 +750,14 @@ async def health_check():
async def chat_endpoint(chat_message: ChatMessage):
"""Main chat endpoint that processes messages and returns AI responses."""
try:
- # Extract and validate message
+ # Toa na thibitisha ujumbe
message = chat_message.message.strip()
if not message:
raise HTTPException(status_code=400, detail="Message cannot be empty")
logger.info(f"Processing message: {message[:50]}...")
- # Call AI service (note: call_llm should be made async for better performance)
+ # Piga huduma ya AI (kumbuka: call_llm inapaswa kufanywa async kwa utendaji bora)
ai_response = await call_llm_async(message, "You are a helpful and friendly assistant.")
logger.info("AI response generated successfully")
@@ -407,213 +775,213 @@ if __name__ == "__main__":
```
**Kuelewa utekelezaji wa FastAPI:**
-- **Inaleta** FastAPI kwa utendakazi wa mfumo wa wavuti wa kisasa na Pydantic kwa uthibitishaji wa data
-- **Inaunda** nyaraka za API kiotomatiki (zinapatikana kwenye `/docs` wakati seva inapoendesha)
-- **Inawezesha** middleware ya CORS kuruhusu maombi ya frontend kutoka asili tofauti
-- **Inafafanua** mifano ya Pydantic kwa uthibitishaji wa maombi/majibu kiotomatiki na nyaraka
-- **Inatumia** endpoints za async kwa utendaji bora na maombi ya wakati mmoja
-- **Inatekeleza** nambari sahihi za hali ya HTTP na usimamizi wa makosa kwa HTTPException
-- **Inajumuisha** ufuatiliaji uliopangwa kwa ufuatiliaji na urekebishaji wa makosa
-- **Inatoa** endpoint ya ukaguzi wa afya kwa ufuatiliaji wa hali ya huduma
-
-**Faida kuu za FastAPI ikilinganishwa na mifumo ya jadi:**
-- **Uthibitishaji wa kiotomatiki**: Mifano ya Pydantic inahakikisha uadilifu wa data kabla ya usindikaji
-- **Nyaraka za kiingiliana**: Tembelea `/docs` kwa nyaraka za API zinazotengenezwa kiotomatiki na zinazoweza kujaribiwa
-- **Usalama wa aina**: Maelezo ya aina ya Python yanazuia makosa ya wakati wa kukimbia na kuboresha ubora wa msimbo
-- **Msaada wa async**: Kushughulikia maombi mengi ya AI kwa wakati mmoja bila kuzuia
-- **Utendaji**: Usindikaji wa maombi kwa kasi zaidi kwa programu za wakati halisi
+- **Inaagiza** FastAPI kwa utendaji wa fremu ya wavuti ya kisasa na Pydantic kwa uthibitishaji wa data
+- **Inaunda** nyaraka za API moja kwa moja (zinapatikana kwenye `/docs` wakati server inapoanza)
+- **Inawezeshwa** CORS middleware kuruhusu maombi ya frontend kutoka asili tofauti
+- **Inaeleza** mifano ya Pydantic kwa uthibitishaji wa maombi/majibu na nyaraka za moja kwa moja
+- **Inatumia** maeneo async kwa utendaji bora na maombi mengi sambamba
+- **Inatekeleza** misimbo sahihi ya hali za HTTP na usimamizi wa makosa kwa HTTPException
+- **Inajumuisha** uandikishaji uliopangwa kwa ajili ya ufuatiliaji na utatuzi wa matatizo
+- **Inatoa** sehemu ya ukaguzi wa afya kwa kufuatilia hali ya huduma
+
+**Faida kuu za FastAPI dhidi ya fremu za kawaida:**
+- **Uthibitishaji moja kwa moja**: Mifano ya Pydantic huhakikisha usahihi wa data kabla ya usindikaji
+- **Nyaraka zenye mwingiliano**: Tembelea `/docs` kupata nyaraka za API zinazotengenezwa na zinaweza kujaribiwa
+- **Usalama wa aina**: Vidokezo vya aina za Python hupunguza makosa ya wakati wa utekelezaji na kuboresha ubora wa msimbo
+- **Msaada wa async**: Hudumia maombi mengi ya AI kwa wakati mmoja bila kuziba
+- **Utendaji**: Usindikaji wa maombi kwa kasi kubwa kwa programu zinazotegemea wakati halisi
### Kuelewa CORS: Mlinzi wa Usalama wa Wavuti
-CORS (Cross-Origin Resource Sharing) ni kama mlinzi wa usalama katika jengo ambaye hukagua ikiwa wageni wanaruhusiwa kuingia. Hebu tuelewe kwa nini hili ni muhimu na jinsi linavyoathiri programu yako.
+CORS (Cross-Origin Resource Sharing) ni kama mlinzi wa usalama kwenye jengo ambaye hakuangalia kama wageni wanaruhusiwa kuingia. Tuelewe kwa nini hii ni muhimu na jinsi inavyoathiri programu yako.
-#### CORS ni nini na Kwa Nini Lipo?
+#### CORS ni Nini na Kwa Nini Ipo?
-**Tatizo**: Fikiria ikiwa tovuti yoyote ingeweza kufanya maombi kwa tovuti ya benki yako kwa niaba yako bila ruhusa yako. Hilo lingekuwa janga la usalama! Vivinjari vinazuia hili kwa default kupitia "Sera ya Asili Moja."
+**Tatizo**: Fikiria kama tovuti yoyote ingekuwa na uwezo wa kutuma maombi kwenye tovuti ya benki yako kwa niaba yako bila idhini yako. Hii ingekuwa shida kubwa ya usalama! Vivinjari huzuia hili kwa kutumia "Sera ya Asili Ileile."
-**Sera ya Asili Moja**: Vivinjari huruhusu kurasa za wavuti kufanya maombi tu kwa kikoa, bandari, na itifaki sawa walizopakiwa kutoka.
+**Sera ya Asili Ileile**: Vivinjari huruhusu kuruhusu kuruka maombi kutoka kwenye tovuti zenye eneo, bandari, na itifaki ile ile waliyoanzia kupakiwa.
-**Mfano wa ulimwengu halisi**: Ni kama usalama wa jengo la ghorofa – ni wakazi tu (asili sawa) wanaweza kufikia jengo kwa default. Ikiwa unataka kumruhusu rafiki (asili tofauti) kutembelea, unahitaji kumwambia mlinzi wa usalama waziwazi kuwa ni sawa.
+**Mfano wa dunia halisi**: Ni kama usalama wa nyumba ya ghorofa – wakazi tu (asilimia ile ile) wanaruhusiwa kuingia. Ukitaka kuruhusu rafiki (asilimia tofauti) kutembelea, lazima umwambie mlinzi waziwazi ni sawa.
-#### CORS katika Mazingira Yako ya Maendeleo
+#### CORS Katika Mazingira Yako ya Maendeleo
-Wakati wa maendeleo, frontend yako na backend yako zinaendesha kwenye bandari tofauti:
+Wakati wa maendeleo, frontend na backend zako zinafanya kazi katika bandari tofauti:
- Frontend: `http://localhost:3000` (au file:// ikiwa unafungua HTML moja kwa moja)
- Backend: `http://localhost:5000`
-Hizi zinachukuliwa kuwa "asili tofauti" hata kama ziko kwenye kompyuta moja!
+Hizi zinachukuliwa kuwa "asilimia tofauti" ingawa ziko kwenye kompyuta ile ile!
```python
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI(__name__)
-CORS(app) # This tells browsers: "It's okay for other origins to make requests to this API"
+CORS(app) # Hii inawaambia vivinjari: "Ni sawa kwa asili nyingine kuomba huduma kwa API hii"
```
-**Kile usanidi wa CORS unachofanya kwa vitendo:**
-- **Huongeza** vichwa maalum vya HTTP kwa majibu ya API yanayoambia vivinjari "ombi hili la asili tofauti linaruhusiwa"
-- **Hushughulikia** maombi ya "preflight" (vivinjari wakati mwingine hukagua ruhusa kabla ya kutuma ombi halisi)
-- **Huzuia** kosa la "kuzuia na sera ya CORS" katika koni ya kivinjari chako
+**Kifanikio cha usanidi wa CORS kwa vitendo:**
+- **Inaongeza** vichwa maalum vya HTTP kwenye majibu ya API vinavyoambia vivinjari "ombi hili la asili tofauti linaruhusiwa"
+- **Inashughulikia** maombi ya "preflight" (vivinjari mara nyingine huchunguza ruhusa kabla ya kutuma ombi halisi)
+- **Inazuia** kosa la "kuzuia sera ya CORS" ambalo linapotokea kwenye koni ya kivinjari chako
-#### Usalama wa CORS: Maendeleo dhidi ya Uzalishaji
+#### Usalama wa CORS: Maendeleo vs Uzalishaji
```python
-# 🚨 Development: Allows ALL origins (convenient but insecure)
+# 🚨 Maendeleo: Inaruhusu vyanzo vyote (rahisi lakini hatari)
CORS(app)
-# ✅ Production: Only allow your specific frontend domain
+# ✅ Uzalishaji: Ruhusu tu eneo lako la frontend lililobainishwa
CORS(app, origins=["https://yourdomain.com", "https://www.yourdomain.com"])
-# 🔒 Advanced: Different origins for different environments
-if app.debug: # Development mode
+# 🔒 Kiwango cha juu: Vyanzo tofauti kwa mazingira tofauti
+if app.debug: # Hali ya maendeleo
CORS(app, origins=["http://localhost:3000", "http://127.0.0.1:3000"])
-else: # Production mode
+else: # Hali ya uzalishaji
CORS(app, origins=["https://yourdomain.com"])
```
-**Kwa nini hili ni muhimu**: Katika maendeleo, `CORS(app)` ni kama kuacha mlango wako wazi – rahisi lakini si salama. Katika uzalishaji, unataka kubainisha ni tovuti gani hasa zinaweza kuzungumza na API yako.
+**Kwa nini hii ni muhimu**: Katika maendeleo, `CORS(app)` ni kama kuacha mlango wa mbele wazi – ndio rahisi lakini si salama. Katika uzalishaji, unataka kutaja ni tovuti gani hasa zinaweza kuongea na API yako.
-#### Matukio ya Kawaida ya CORS na Suluhisho
+#### Hali za Kawaida za CORS na Suluhisho
| Hali | Tatizo | Suluhisho |
-|------|--------|----------|
-| **Maendeleo ya Kawaida** | Frontend haiwezi kufikia backend | Ongeza CORSMiddleware kwa FastAPI |
-| **GitHub Pages + Heroku** | Frontend iliyotumwa haiwezi kufikia API | Ongeza URL ya GitHub Pages yako kwa asili za CORS |
-| **Kikoa Maalum** | Makosa ya CORS katika uzalishaji | Sasisha asili za CORS ili zilingane na kikoa chako |
-| **Programu ya Simu** | Programu haiwezi kufikia API ya wavuti | Ongeza kikoa cha programu yako au tumia `*` kwa uangalifu |
+|----------|---------|----------|
+| **Maendeleo ya Ndani (Local Development)** | Frontend haiwezi kufikia backend | Ongeza CORSMiddleware kwenye FastAPI |
+| **GitHub Pages + Heroku** | Frontend iliyowekwa haitumii API | Ongeza URL ya GitHub Pages kwenye asili za CORS |
+| **Domeni Maalum** | Makosa ya CORS uzalishaji | Sasisha asili za CORS kulingana na domeni yako |
+| **Programu ya Simu** | Programu haiwezi kufikia API ya wavuti | Ongeza domeni ya programu yako au tumia `*` kwa uangalifu |
-**Kidokezo cha kitaalamu**: Unaweza kuangalia vichwa vya CORS katika Zana za Wasanidi wa kivinjari chako chini ya kichupo cha Mtandao. Tafuta vichwa kama `Access-Control-Allow-Origin` katika majibu.
+**Ushauri mzuri**: Unaweza kuangalia vichwa vya CORS kwenye zana za Watengenezaji wa kivinjari chako chini ya kichupo cha Mtandao. Tafuta vichwa kama `Access-Control-Allow-Origin` kwenye jibu.
-### Usimamizi wa Makosa na Uthibitishaji
+### Ushughulikiaji wa Makosa na Uthibitishaji
-Angalia jinsi API yetu inavyoshirikisha usimamizi sahihi wa makosa:
+Angalia jinsi API yetu inavyoshughulikia makosa kwa usahihi:
```python
-# Validate that we received a message
+# Thibitisha kwamba tumepokea ujumbe
if not message:
return jsonify({"error": "Message field is required"}), 400
```
**Kanuni kuu za uthibitishaji:**
-- **Hukagua** uwanja unaohitajika kabla ya kusindika maombi
+- **Huthibitisha** viwanja muhimu kabla ya kusindika maombi
- **Hurejesha** ujumbe wa makosa wenye maana katika muundo wa JSON
-- **Hutumia** nambari sahihi za hali ya HTTP (400 kwa maombi mabaya)
-- **Hutoa** maoni wazi kusaidia wasanidi wa frontend kurekebisha masuala
+- **Inatumia** misimbo sahihi ya hali ya HTTP (400 kwa maombi mabaya)
+- **Hutoa** mrejesho wazi kusaidia waendelezaji wa frontend kutatua matatizo
## Kuweka na Kuendesha Backend Yako
-Sasa kwa kuwa tuna muunganisho wetu wa AI na seva ya FastAPI tayari, hebu tuanze kila kitu. Mchakato wa usanidi unahusisha kusakinisha utegemezi wa Python, kusanidi vigezo vya mazingira, na kuanzisha seva yako ya maendeleo.
+Sasa tunapokuwa na uingizaji wetu wa AI na server ya FastAPI tayari, tuanzishe kila kitu kilicho tayari. Mchakato wa usanikishaji unahusisha kusakinisha maktaba za Python, kusanidi mabadiliko ya mazingira, na kuanzisha server yako ya maendeleo.
-### Usanidi wa Mazingira ya Python
+### Kuanzisha Mazingira ya Python
-Hebu tusanidi mazingira yako ya maendeleo ya Python. Mazingira ya kawaida ni kama mbinu ya mradi wa Manhattan – kila mradi unapata nafasi yake ya pekee na zana maalum na utegemezi, kuzuia migongano kati ya miradi tofauti.
+Tuwashie mazingira ya maendeleo ya Python. Mazingira ya virtual ni kama mpango wa Manhattan uliogawanywa sehemu – kila mradi unapata nafasi yake pekee ya pekee yenye zana maalum na utegemezi, kuzuia migongano kati ya miradi tofauti.
```bash
-# Navigate to your backend directory
+# Elekea kwenye saraka yako ya nyuma
cd backend
-# Create a virtual environment (like creating a clean room for your project)
+# Unda mazingira ya kweli (kama kuunda chumba safi kwa mradi wako)
python -m venv venv
-# Activate it (Linux/Mac)
+# Iwasha (Linux/Mac)
source ./venv/bin/activate
-# On Windows, use:
+# Kwenye Windows, tumia:
# venv\Scripts\activate
-# Install the good stuff
+# Sakinisha vitu vizuri
pip install openai fastapi uvicorn python-dotenv
```
-**Kile tulichofanya:**
-- **Tumeunda** Bubble yetu ya Python ambapo tunaweza kusakinisha vifurushi bila kuathiri chochote kingine
-- **Tumeiwezesha** ili terminal yetu ijue kutumia mazingira haya maalum
-- **Tumesakinisha** vitu muhimu: OpenAI kwa uchawi wa AI, FastAPI kwa API yetu ya wavuti, Uvicorn kuendesha, na python-dotenv kwa usimamizi salama wa siri
+**Tulichofanya sasa hivi:**
+- **Tumeunda** povu yetu ndogo ya Python ambapo tunaweza kusakinisha maktaba bila kuathiri vingine
+- **Tumezikwa** ili terminal yetu ijue kutumia mazingira haya maalum
+- **Tumefunga** muhimu: OpenAI kwa uchawi wa AI, FastAPI kwa API yetu ya wavuti, Uvicorn kuendesha server, na python-dotenv kwa usimamizi wa siri salama
-**Utegemezi muhimu umeelezwa:**
-- **FastAPI**: Mfumo wa wavuti wa kisasa, wa haraka na nyaraka za API kiotomatiki
-- **Uvicorn**: Seva ya ASGI yenye kasi inayoweza kuendesha programu za FastAPI
-- **OpenAI**: Maktaba rasmi kwa GitHub Models na muunganisho wa API ya OpenAI
-- **python-dotenv**: Upakiaji salama wa vigezo vya mazingira kutoka kwa faili za .env
+**Marekebisho muhimu yaliyoelezwa:**
+- **FastAPI**: Fremu ya kisasa, yenye kasi ya wavuti na nyaraka za API za moja kwa moja
+- **Uvicorn**: Server ya ASGI yenye kasi mno inayochukua na kuendesha programu za FastAPI
+- **OpenAI**: Maktaba rasmi kwa modeli za GitHub na API ya OpenAI
+- **python-dotenv**: Kubeba mabadiliko ya mazingira kwa usalama kutoka kwa faili `.env`
-### Usanidi wa Mazingira: Kuhifadhi Siri Salama
+### Usanidi wa Mazingira: Kuzingatia Siri Salama
-Kabla ya kuanza API yetu, tunahitaji kuzungumzia mojawapo ya masomo muhimu zaidi katika maendeleo ya wavuti: jinsi ya kuhifadhi siri zako salama. Vigezo vya mazingira ni kama chumba cha usalama ambacho programu yako pekee inaweza kufikia.
+Kabla hatujaanza API yetu, tunahitaji kujadili moja ya masomo muhimu zaidi katika maendeleo ya wavuti: jinsi ya kuweka siri zako kweli zisiwe wazi. Mabadiliko ya mazingira ni kama sefeli salama ambayo programu yako tu inaweza kufikia.
-#### Vigezo vya Mazingira ni Nini?
+#### Mabadiliko ya Mazingira ni Nini?
-**Fikiria vigezo vya mazingira kama sanduku la usalama** – unaweka vitu vyako vya thamani humo, na ni wewe tu (na programu yako) unayeweza kufungua. Badala ya kuandika taarifa nyeti moja kwa moja kwenye msimbo wako (ambapo kila mtu anaweza kuiona), unaihifadhi salama katika mazingira.
+**Fikiria mabadiliko ya mazingira kama sanduku la amana salama** – unailaza vitu vyako vya thamani humo, na wewe tu (na programu yako) una funguo la kuipata. Badala ya kuandika taarifa nyeti moja kwa moja kwenye msimbo wako (ambapo mtu yeyote anaweza kuiona), unahifadhi kwa usalama katika mazingira.
-**Hii ndiyo tofauti:**
-- **Njia mbaya**: Kuandika nywila yako kwenye karatasi ya kunata na kuiweka kwenye skrini yako
-- **Njia sahihi**: Kuhifadhi nywila yako katika meneja wa nywila salama ambao ni wewe tu unayeweza kufikia
+**Hii ndio tofauti:**
+- **Njia mbaya**: Kuandika nenosiri lako kwenye karatasi na kuiweka kwenye skrini yako ya kompyuta
+- **Njia sahihi**: Kuweka nenosiri lako kwenye meneja wa nenosiri salama unayemiliki wewe peke yako
-#### Kwa Nini Vigezo vya Mazingira ni Muhimu
+#### Kwa Nini Mabadiliko ya Mazingira Ni Muhimu
```python
-# 🚨 NEVER DO THIS - API key visible to everyone
+# 🚨 USIFANYE HIVYO - Fikira la API linaonekana kwa kila mtu
client = OpenAI(
- api_key="ghp_1234567890abcdef...", # Anyone can steal this!
+ api_key="ghp_1234567890abcdef...", # Mtu yeyote anaweza kuiba hii!
base_url="https://models.github.ai/inference"
)
-# ✅ DO THIS - API key stored securely
+# ✅ FANYA HIVYO - Fikira la API lihifadhiwe kwa usalama
client = OpenAI(
- api_key=os.environ["GITHUB_TOKEN"], # Only your app can access this
+ api_key=os.environ["GITHUB_TOKEN"], # Ni programu yako tu inaweza kufikia hii
base_url="https://models.github.ai/inference"
)
```
-**Kinachotokea unapoweka siri moja kwa moja kwenye msimbo:**
-1. **Ufunuo wa udhibiti wa toleo**: Mtu yeyote mwenye ufikiaji wa hifadhi yako ya Git anaona API key yako
-2. **Hifadhi za umma**: Ukisukuma kwenye GitHub, key yako inaonekana kwa mtandao mzima
-3. **Kushiriki timu**: Wasanidi wengine wanaofanya kazi kwenye mradi wako wanapata ufikiaji wa API key yako ya kibinafsi
-4. **Uvunjaji wa usalama**: Ikiwa mtu ataiba API key yako, anaweza kutumia mikopo yako ya AI
+**Kinachotokea ukiandika siri moja kwa moja:**
+1. **Ufunuo kwa usimamizi wa toleo**: Yeyote aliye na ufikiaji wa hifadhi yako ya Git anaona ufunguo wako wa API
+2. **Hifadhi za umma**: Ukiweka kwenye GitHub, ufunguo wako unaonekana kwa kila mtu mtandaoni
+3. **Kushirikiana kwa timu**: Waendelezaji wengine kwenye mradi wako wanapata ufunguo wako wa API binafsi
+4. **Uvunjaji wa usalama**: Ikiwa mtu ataiba ufunguo wako wa API, anaweza kutumia mikopo yako ya AI
-#### Kuunda Faili Yako ya Mazingira
+#### Kuunda Faili Yako la Mazingira `.env`
-Unda faili `.env` katika saraka ya backend yako. Faili hii huhifadhi siri zako kwa ndani:
+Tengeneza faili `.env` katika saraka ya backend yako. Faili hii huhifadhi siri zako ndani ya kompyuta:
```bash
-# .env file - This should NEVER be committed to Git
+# Faili la .env - Hili HAUWASHWI kamwe kupelekwa kwenye Git
GITHUB_TOKEN=your_github_personal_access_token_here
FASTAPI_DEBUG=True
ENVIRONMENT=development
```
-**Kuelewa faili ya .env:**
-- **Siri moja kwa kila mstari** katika muundo wa `KEY=value`
-- **Hakuna nafasi** karibu na alama ya usawa
-- **Hakuna nukuu** zinazohitajika karibu na maadili (kawaida)
+**Kuelewa faili la .env:**
+- **Siri moja kwa mstari** katika muundo wa `KEY=value`
+- **Hakuna nafasi** karibu na alama ya sawa
+- **Hakuna nukuu** zinahitajika kwenye thamani (kawaida)
- **Maoni** huanza na `#`
-#### Kuunda Tokeni Yako ya Ufikiaji wa Kibinafsi ya GitHub
+#### Kuunda Tokeni Yako Binafsi ya Kufikia GitHub
-Tokeni yako ya GitHub ni kama nywila maalum inayotoa ruhusa kwa programu yako kutumia huduma za AI za GitHub:
+Tokeni yako ya GitHub ni kama nenosiri maalum linaloruhusu programu yako kutumia huduma za AI za GitHub:
**Hatua kwa hatua kuunda tokeni:**
-1. **Nenda kwa Mipangilio ya GitHub** → Mipangilio ya msanidi programu → Tokeni za ufikiaji wa kibinafsi → Tokeni (classic)
+1. **Nenda kwenye Mipangilio ya GitHub** → Mipangilio ya mtengenezaji → Tokeni za huduma binafsi → Tokeni (classic)
2. **Bonyeza "Generate new token (classic)"**
-3. **Weka muda wa kuisha** (siku 30 kwa majaribio, muda mrefu kwa uzalishaji)
-4. **Chagua maeneo**: Angalia "repo" na ruhusa nyingine unazohitaji
-5. **Tengeneza tokeni** na nakili mara moja (huwezi kuiona tena!)
-6. **Bandika kwenye faili yako ya .env**
+3. **Weka muda wa kumalizika** (siku 30 kwa majaribio, muda mrefu kwa uzalishaji)
+4. **Chagua wigo**: Angalia "repo" na ruhusa zingine unazohitaji
+5. **Tengeneza tokeni** na uibandike mara moja (hauna tena ruhusa ya kuiona!)
+6. **Mweka kwenye faili lako la .env**
```bash
-# Example of what your token looks like (this is fake!)
+# Mfano wa jinsi tokeni yako inavyoonekana (hii ni feki!)
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R
```
-#### Kupakia Vigezo vya Mazingira katika Python
+#### Kupakia Mabadiliko ya Mazingira katika Python
```python
import os
from dotenv import load_dotenv
-# Load environment variables from .env file
+# Pakia mabadiliko ya mazingira kutoka kwa faili la .env
load_dotenv()
-# Now you can access them securely
+# Sasa unaweza kuyafikia kwa usalama
api_key = os.environ.get("GITHUB_TOKEN")
if not api_key:
raise ValueError("GITHUB_TOKEN not found in environment variables!")
@@ -624,18 +992,18 @@ client = OpenAI(
)
```
-**Kile msimbo huu unafanya:**
-- **Unapakia** faili yako ya .env na kufanya vigezo kupatikana kwa Python
-- **Hukagua** ikiwa tokeni inayohitajika ipo (usimamizi mzuri wa makosa!)
-- **Inainua** kosa wazi ikiwa tokeni haipo
-- **Inatumia** tokeni kwa usalama bila kuifunua kwenye msimbo
+**Msimbo huu unafanya:**
+- **Unapakia** faili lako la .env na kufanya mabadiliko kupatikana kwa Python
+- **Huthibitisha** kama tokeni muhimu ipo (ushughulikiaji mzuri wa makosa!)
+- **Hutoa** kosa la wazi ikiwa tokeni haipo
+- **Inatumia** tokeni kwa usalama bila kuionyesha kwenye msimbo
-#### Usalama wa Git: Faili ya .gitignore
+#### Usalama wa Git: Faili la .gitignore
-Faili yako ya `.gitignore` inaambia Git ni faili zipi zisizo na haja ya kufuatiliwa au kupakiwa:
+Faili lako la `.gitignore` linaambia Git ni faili gani isizotakwa kufuatiliwa au kupakiwa:
```bash
-# .gitignore - Add these lines
+# .gitignore - Ongeza mistari hii
.env
*.env
.env.local
@@ -645,57 +1013,56 @@ venv/
.vscode/
```
-**Kwa nini hili ni muhimu**: Mara tu unapoongeza `.env` kwa `.gitignore`, Git itapuuza faili yako ya mazingira, kuzuia wewe kupakia siri zako kwa GitHub kwa bahati mbaya.
+**Kwa nini hii ni muhimu**: Mara tu unapoongeza `.env` kwenye `.gitignore`, Git itapuuzia faili lako la mazingira, ikuzuia kupakia siri zako kwa bahati mbaya kwenye GitHub.
#### Mazingira Tofauti, Siri Tofauti
-Programu za kitaalamu hutumia API key tofauti kwa mazingira tofauti:
+Programu za kitaalamu hutumia funguo tofauti za API kwa mazingira tofauti:
```bash
-# .env.development
+# .env.kuendeleza
GITHUB_TOKEN=your_development_token
DEBUG=True
-# .env.production
+# .env.utengenezaji
GITHUB_TOKEN=your_production_token
DEBUG=False
```
-**Kwa nini hili ni muhimu**: Hutaki majaribio yako ya maendeleo yaathiri kiwango chako cha matumizi ya AI ya uzalishaji, na unataka viwango tofauti vya usalama kwa mazingira tofauti.
+**Kwa nini hii ni muhimu**: Hutaki majaribio ya maendeleo kuathiri msamaha wako wa matumizi ya AI wa uzalishaji, na unataka viwango tofauti vya usalama kwa mazingira tofauti.
-### Kuanzisha Seva Yako ya Maendeleo: Kuleta FastAPI Yako Hai
-
-Sasa ni wakati wa kusisimua – kuanzisha seva yako ya maendeleo ya FastAPI na kuona muunganisho wako wa AI ukifanya kazi! FastAPI inatumia Uvicorn, seva ya ASGI yenye kasi iliyoundwa mahsusi kwa programu za Python za async.
+### Kuanzisha Server ya Maendeleo: Kuleta FastAPI Yako Kuishi
+Sasa inakuja wakati wa kusisimua – kuanzisha seva yako ya maendeleo ya FastAPI na kuona muunganisho wako wa AI ukiamka hai! FastAPI hutumia Uvicorn, seva ya ASGI yenye mwendo wa mwanga ambayo imeundwa mahsusi kwa programu za Python async.
#### Kuelewa Mchakato wa Kuanzisha Seva ya FastAPI
```bash
-# Method 1: Direct Python execution (includes auto-reload)
+# Njia 1: Utekelezaji wa moja kwa moja wa Python (inajumuisha upya-ziada wa moja kwa moja)
python api.py
-# Method 2: Using Uvicorn directly (more control)
+# Njia 2: Kutumia Uvicorn moja kwa moja (udhibiti zaidi)
uvicorn api:app --host 0.0.0.0 --port 5000 --reload
```
-Unapoendesha amri hii, haya ndiyo yanayotokea nyuma ya pazia:
+Unapoendesha amri hii, hapa ndilo linatokea nyuma ya pazia:
-**1. Python inapakua programu yako ya FastAPI**:
-- Inaleta maktaba zote zinazohitajika (FastAPI, Pydantic, OpenAI, nk.)
-- Inapakia vigezo vya mazingira kutoka kwa faili yako ya `.env`
-- Inaunda mfano wa programu ya FastAPI na nyaraka za kiotomatiki
+**1. Python inapakia programu yako ya FastAPI**:
+- Inaingiza maktaba zote muhimu (FastAPI, Pydantic, OpenAI, n.k.)
+- Inapakia mabadiliko ya mazingira kutoka kwa faili yako `.env`
+- Inatengeneza mfano wa programu ya FastAPI na nyaraka za moja kwa moja
-**2. Uvicorn inasanidi seva ya ASGI**:
-- Inaunganisha na bandari ya 5000 na uwezo wa kushughulikia maombi ya async
-- Inasanidi uelekezaji wa maombi na uthibitishaji wa kiotomatiki
-- Inawezesha upakiaji wa haraka kwa maendeleo (kuanzisha upya mabadiliko ya faili)
-- Inazalisha nyaraka za API zinazoweza kuingiliana
+**2. Uvicorn huandaa seva ya ASGI**:
+- Inajihusisha na bandari 5000 na uwezo wa kushughulikia maombi async
+- Inaweka njia za kuongoza maombi na uhakikisho wa moja kwa moja
+- Inawezeshwa upya moja kwa moja kwa maendeleo (huanzisha upya faili zinapobadilika)
+- Inazalisha nyaraka za API zenye mwingiliano
**3. Seva inaanza kusikiliza**:
- Terminal yako inaonyesha: `INFO: Uvicorn running on http://0.0.0.0:5000`
-- Seva inaweza kushughulikia maombi mengi ya AI kwa wakati mmoja
-- API yako iko tayari na nyaraka za kiotomatiki kwenye `http://localhost:5000/docs`
+- Seva inaweza kushughulikia maombi mengi ya AI sambamba
+- API yako iko tayari na nyaraka za moja kwa moja kwenye `http://localhost:5000/docs`
-#### Kile Unachopaswa Kuona Wakati Kila Kitu Kinafanya Kazi
+#### Unapaswa Kuona Nini Wakati Kila Kitu Kinafanya Kazi
```bash
$ python api.py
@@ -708,27 +1075,45 @@ INFO: Application startup complete.
```
**Kuelewa matokeo ya FastAPI:**
-- **Itatazama mabadiliko**: Upakiaji wa kiotomatiki umewezeshwa kwa maendeleo
-- **Uvicorn inaendesha**: Seva ya ASGI yenye utendaji wa juu iko hai
-- **Mchakato wa upakiaji upya umeanza**: Mfuatiliaji wa faili kwa kuanzisha upya kiotomatiki
-- **Kuanzisha programu kumekamilika**: Programu ya FastAPI imeanzishwa kwa mafanikio
-- **Nyaraka za kiingiliana zinapatikana**: Tembelea `/docs` kwa nyaraka za API kiotomatiki
+- **Itatazama mabadiliko**: Auto-reload imewezeshwa kwa maendeleo
+- **Uvicorn inafanya kazi**: Seva ya ASGI yenye utendaji mkubwa inatumika
+- **Mchakato wa reloader umeanzishwa**: Mtafiti wa faili kwa kuanzisha upya moja kwa moja
+- **Mwanzo wa programu umekamilika**: App ya FastAPI imezinduliwa kwa mafanikio
+- **Nyaraka za mwingiliano zinapatikana**: Tembelea `/docs` kwa nyaraka za API za moja kwa moja
+
+#### Kupima FastAPI Yako: Njia Nyingi Zenye Nguvu
+
+FastAPI hutoa njia kadhaa rahisi za kupima API yako, ikiwa ni pamoja na nyaraka za mwingiliano za moja kwa moja:
+
+**Njia 1: Nyaraka za Mwingiliano za API (Inapendekezwa)**
+1. Fungua kivinjari chako na nenda `http://localhost:5000/docs`
+2. Utaona Swagger UI na mwisho wote wako umeandikwa
+3. Bonyeza `/hello` → "Try it out" → Andika ujumbe wa majaribio → "Execute"
+4. Tazama jibu moja kwa moja kwenye kivinjari kwa muundo sahihi
+
+**Njia 2: Jaribio la Kivinjari la Msingi**
+1. Nenda `http://localhost:5000` kwa mwisho wa mzizi
+2. Nenda `http://localhost:5000/health` kuangalia afya ya seva
+3. Hii inathibitisha seva yako ya FastAPI inafanya kazi vizuri
-#### Kujaribu FastAPI Yako: Njia Nyingi Zenye Nguvu
+**Njia 2: Jaribio la Line ya Amri (Zaidi)**
+```bash
+# Jaribu kwa kutumia curl (ikiwa inapatikana)
+curl -X POST http://localhost:5000/hello \
+ -H "Content-Type: application/json" \
+ -d '{"message": "Hello AI!"}'
-FastAPI inatoa njia kadhaa rahisi za kujaribu API yako, ikiwa ni pamoja na nyaraka za kiotomatiki zinazoweza kuingiliana:
+# Jibu linalotarajiwa:
+# {"response": "Habari! Mimi ni msaidizi wako wa AI. Naweza kukusaidiaje leo?"}
+```
-**Njia ya 1: Nyaraka za API Zinazoweza Kuingiliana (Inapendekezwa)**
-1. Fungua kivinjari chako na nenda kwa `http://localhost:5000/docs`
-2. Utaona Swagger UI na endpoints zako zote zikiwa zimeandikwa
-3. Bonyeza kwenye `/hello` → "Jaribu" → Weka ujumbe wa majaribio → "Tekeleza"
-4. Tazama majibu moja kwa moja
+**Njia 3: Skripti ya Jaribio la Python**
```python
-# test_api.py - Create this file to test your API
+# test_api.py - Unda faili hili kupima API yako
import requests
import json
-# Test the API endpoint
+# Pima mwisho wa API
url = "http://localhost:5000/hello"
data = {"message": "Tell me a joke about programming"}
@@ -740,34 +1125,34 @@ else:
print("Error:", response.status_code, response.text)
```
-#### Kutatua Masuala ya Kawaida ya Kuanza
+#### Kutatua Tatizo la Kawaida la Mwanzo
-| Ujumbe wa Kosa | Maana Yake | Jinsi ya Kurekebisha |
-|----------------|------------|-----------------------|
-| `ModuleNotFoundError: No module named 'fastapi'` | FastAPI haijasakinishwa | Run `pip install fastapi uvicorn` katika mazingira yako ya virtual |
-| `ModuleNotFoundError: No module named 'uvicorn'` | ASGI server haijasakinishwa | Run `pip install uvicorn` katika mazingira yako ya virtual |
-| `KeyError: 'GITHUB_TOKEN'` | Kigezo cha mazingira hakijapatikana | Angalia faili yako ya `.env` na wito wa `load_dotenv()` |
-| `Address already in use` | Bandari 5000 inatumika | Zima michakato mingine inayotumia bandari 5000 au badilisha bandari |
-| `ValidationError` | Data ya ombi haifanani na modeli ya Pydantic | Hakikisha muundo wa ombi lako unalingana na schema inayotarajiwa |
-| `HTTPException 422` | Kitu kisichoweza kusindika | Uthibitishaji wa ombi umeshindwa, angalia `/docs` kwa muundo sahihi |
-| `OpenAI API error` | Uthibitishaji wa huduma ya AI umeshindwa | Hakikisha token yako ya GitHub ni sahihi na ina ruhusa zinazofaa |
+| Ujumbe wa Hitilafu | Kinachomaanisha | Jinsi ya Kurekebisha |
+|---------------|---------------|------------|
+| `ModuleNotFoundError: No module named 'fastapi'` | FastAPI haijasakinishwa | Endesha `pip install fastapi uvicorn` kwenye mazingira yako ya virtual |
+| `ModuleNotFoundError: No module named 'uvicorn'` | Seva ya ASGI haijasakinishwa | Endesha `pip install uvicorn` kwenye mazingira yako ya virtual |
+| `KeyError: 'GITHUB_TOKEN'` | Kigezo cha mazingira hakipatikani | Angalia faili yako `.env` na mwito wa `load_dotenv()` |
+| `Address already in use` | Bandari 5000 inatumika | Funga mchakato mwingine unaotumia bandari 5000 au badilisha bandari |
+| `ValidationError` | Data ya ombi hailingani na mfano wa Pydantic | Angalia muundo wa ombi lako unaendana na skimu inayotarajiwa |
+| `HTTPException 422` | Kiumbe kisichoshughulikiwa | Uhakiki wa ombi umefaulu, angalia `/docs` kwa muundo sahihi |
+| `OpenAI API error` | Huduma ya AI imeshindwa kuthibitishwa | Hakikisha tokeni yako ya GitHub ni sahihi na ina ruhusa sahihi |
-#### Mazoea Bora ya Maendeleo
+#### Miongozo Bora ya Maendeleo
-**Hot Reloading**: FastAPI na Uvicorn hutoa upakiaji wa moja kwa moja unapohifadhi mabadiliko kwenye faili zako za Python. Hii inamaanisha unaweza kurekebisha msimbo wako na kujaribu mara moja bila kuanzisha tena kwa mikono.
+**Upakiaji Moto**: FastAPI na Uvicorn hutoa upakiaji wa moja kwa moja unapohifadhi mabadiliko kwenye faili zako za Python. Hii inamaanisha unaweza kubadilisha msimbo na kupima mara moja bila kuanzisha upya kwa mkono.
```python
-# Enable hot reloading explicitly
+# Wezesha upakiaji wa moto kwa uwazi
if __name__ == "__main__":
- app.run(host="0.0.0.0", port=5000, debug=True) # debug=True enables hot reload
+ app.run(host="0.0.0.0", port=5000, debug=True) # debug=True inaruhusu upakiaji wa moto
```
-**Kuweka kumbukumbu kwa Maendeleo**: Ongeza kumbukumbu ili kuelewa kinachoendelea:
+**Kuinua kumbukumbu kwa Maendeleo**: Ongeza kumbukumbu ili kuelewa kinachoendelea:
```python
import logging
-# Set up logging
+# Weka upigaji taarifa
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
@@ -791,21 +1176,21 @@ def hello():
return jsonify({"error": "AI service temporarily unavailable"}), 500
```
-**Kwa nini kuweka kumbukumbu kunasaidia**: Wakati wa maendeleo, unaweza kuona hasa ni maombi gani yanayoingia, ni nini AI inajibu, na wapi makosa yanatokea. Hii inafanya utatuzi kuwa wa haraka zaidi.
+**Kwa nini kumbukumbu husaidia**: Wakati wa maendeleo, unaweza kuona hasa maombi yanayokuja, AI inajibu vipi, na mahali pa kutokea kwa makosa. Hii hufanya utambuzi wa hitilafu kuwa wa kasi zaidi.
-### Kuseti kwa GitHub Codespaces: Maendeleo ya Wingu Rahisi
+### Kusanidi kwa GitHub Codespaces: Maendeleo ya Wingu Yaliyorahisishwa
-GitHub Codespaces ni kama kuwa na kompyuta yenye nguvu ya maendeleo kwenye wingu ambayo unaweza kufikia kutoka kwa kivinjari chochote. Ikiwa unafanya kazi katika Codespaces, kuna hatua kadhaa za ziada za kufanya backend yako ipatikane kwa frontend yako.
+GitHub Codespaces ni kama kuwa na kompyuta yenye nguvu ya maendeleo kwenye wingu unayoweza kufikia kutoka kivinjari chochote. Ikiwa unafanya kazi ndani ya Codespaces, kuna hatua chache za ziada za kufanya backend yako ipatikane kwa frontend yako.
#### Kuelewa Mtandao wa Codespaces
-Katika mazingira ya maendeleo ya ndani, kila kitu kinaendeshwa kwenye kompyuta moja:
+Katika mazingira ya maendeleo ya ndani, kila kitu kinaendeshwa kwenye kompyuta ile ile:
- Backend: `http://localhost:5000`
- Frontend: `http://localhost:3000` (au file://)
-Katika Codespaces, mazingira yako ya maendeleo yanaendeshwa kwenye seva za GitHub, kwa hivyo "localhost" ina maana tofauti. GitHub huunda URLs za umma kwa huduma zako kiotomatiki, lakini unahitaji kuzisanidi ipasavyo.
+Katika Codespaces, mazingira yako ya maendeleo yanaendeshwa kwenye seva za GitHub, hivyo "localhost" ina maana tofauti. GitHub hutengeneza URL za umma kwa huduma zako kwa moja, lakini unahitaji kuziweka ipasavyo.
-#### Hatua kwa Hatua ya Usanidi wa Codespaces
+#### Usaidizi wa Hatua kwa Hatua wa Codespaces
**1. Anzisha seva yako ya backend**:
```bash
@@ -813,51 +1198,51 @@ cd backend
python api.py
```
-Utaona ujumbe wa kawaida wa kuanza wa FastAPI/Uvicorn, lakini tambua kuwa inaendeshwa ndani ya mazingira ya Codespace.
+Utaona ujumbe wa kuanzisha FastAPI/Uvicorn unaofahamika, lakini ukumbuke iko ndani ya mazingira ya Codespace.
-**2. Sanidi mwonekano wa bandari**:
-- Tafuta tabo ya "Ports" kwenye paneli ya chini ya VS Code
+**2. Sanidi uonekano wa bandari**:
+- Tafuta kichupo cha "Ports" kwenye paneli ya chini ya VS Code
- Tafuta bandari 5000 kwenye orodha
- Bonyeza kulia kwenye bandari 5000
- Chagua "Port Visibility" → "Public"
-**Kwa nini kuifanya iwe ya umma?** Kwa kawaida, bandari za Codespace ni za kibinafsi (zinapatikana tu kwako). Kuzifanya za umma kunaruhusu frontend yako (ambayo inaendeshwa kwenye kivinjari) kuwasiliana na backend yako.
+**Kwa nini kuweka umma?** Kwa kawaida, bandari za Codespace ni za faragha (zinapatikana kwako tu). Kuweka umma kunaruhusu frontend yako (inayoendesha kwenye kivinjari) kuwasiliana na backend yako.
**3. Pata URL yako ya umma**:
-Baada ya kufanya bandari iwe ya umma, utaona URL kama:
+Baada ya kuweka bandari kuwa umma, utaona URL kama hii:
```
https://your-codespace-name-5000.app.github.dev
```
**4. Sasisha usanidi wa frontend yako**:
```javascript
-// In your frontend app.js, update the BASE_URL:
+// Katika app.js ya frontend yako, sasisha BASE_URL:
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";
```
-#### Kuelewa URLs za Codespace
+#### Kuelewa URL za Codespace
-URLs za Codespace zinafuata muundo unaotabirika:
+URL za Codespace zina muundo unaotabirika:
```
https://[codespace-name]-[port].app.github.dev
```
-**Kuvunja hii:**
-- `codespace-name`: Kitambulisho cha kipekee cha Codespace yako (kwa kawaida kinajumuisha jina lako la mtumiaji)
-- `port`: Namba ya bandari ambayo huduma yako inaendeshwa (5000 kwa programu yetu ya FastAPI)
+**Kuvunja haya:**
+- `codespace-name`: Kitambulisho cha kipekee kwa Codespace yako (kawaida kina jina la mtumiaji wako)
+- `port`: Nambari ya bandari huduma yako inayoendeshwa (5000 kwa app yetu ya FastAPI)
- `app.github.dev`: Kikoa cha GitHub kwa programu za Codespace
-#### Kujaribu Usanidi wa Codespace Yako
+#### Kupima Usanidi wako wa Codespace
**1. Jaribu backend moja kwa moja**:
-Fungua URL yako ya umma kwenye tabo mpya ya kivinjari. Unapaswa kuona:
+Fungua URL yako ya umma kwa kichupo kipya cha kivinjari. Unapaswa kuona:
```
Welcome to the AI Chat API. Send POST requests to /hello with JSON payload containing 'message' field.
```
-**2. Jaribu na zana za msanidi wa kivinjari**:
+**2. Jaribu na zana za mende wa kivinjari**:
```javascript
-// Open browser console and test your API
+// Fungua console ya kivinjari na jaribu API yako
fetch('https://your-codespace-name-5000.app.github.dev/hello', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
@@ -867,101 +1252,123 @@ fetch('https://your-codespace-name-5000.app.github.dev/hello', {
.then(data => console.log(data));
```
-#### Codespaces vs Maendeleo ya Ndani
+#### Codespaces dhidi ya Maendeleo ya Ndani
| Kipengele | Maendeleo ya Ndani | GitHub Codespaces |
-|-----------|--------------------|-------------------|
-| **Muda wa Usanidi** | Mrefu (sakinisha Python, utegemezi) | Papo hapo (mazingira yaliyosanidiwa awali) |
-| **Ufikiaji wa URL** | `http://localhost:5000` | `https://xyz-5000.app.github.dev` |
-| **Usanidi wa Bandari** | Kiotomatiki | Mwongozo (fanya bandari ziwe za umma) |
-| **Uhifadhi wa Faili** | Kompyuta ya ndani | Hifadhi ya GitHub |
-| **Ushirikiano** | Ngumu kushiriki mazingira | Rahisi kushiriki kiungo cha Codespace |
-| **Utegemezi wa Mtandao** | Kwa simu za API za AI pekee | Inahitajika kwa kila kitu |
+|--------|-------------------|-------------------|
+| **Muda wa Usanidi** | Mrefu (sasisha Python, utegemezi) | Mara moja (mazingira tayari yamesanidiwa) |
+| **Upatikanaji wa URL** | `http://localhost:5000` | `https://xyz-5000.app.github.dev` |
+| **Usanidi wa Bandari** | Moja kwa moja | Mikono (weka bandari kuwa za umma) |
+| **Uendelevu wa Faili** | Kompyuta ya ndani | Rejesta ya GitHub |
+| **Ushirikiano** | Gumu kushiriki mazingira | Rahisi kushiriki kiungo cha Codespace |
+| **Utegemezi wa Intaneti** | Kwa maombi ya API ya AI pekee | Inahitajika kwa kila kitu |
#### Vidokezo vya Maendeleo ya Codespace
-**Vigezo vya Mazingira katika Codespaces**:
-Faili yako ya `.env` inafanya kazi kwa njia sawa katika Codespaces, lakini unaweza pia kuweka vigezo vya mazingira moja kwa moja katika Codespace:
+**Mabadiliko ya Mazingira katika Codespaces**:
+Faili yako `.env` inafanya kazi sawa ndani ya Codespaces, lakini pia unaweza kuweka vigezo vya mazingira moja kwa Codespace:
```bash
-# Set environment variable for the current session
+# Weka thamani ya mazingira kwa kikao cha sasa
export GITHUB_TOKEN="your_token_here"
-# Or add to your .bashrc for persistence
+# Au ongeza kwenye .bashrc yako kwa kudumu
echo 'export GITHUB_TOKEN="your_token_here"' >> ~/.bashrc
```
**Usimamizi wa Bandari**:
-- Codespaces hugundua kiotomatiki wakati programu yako inaanza kusikiliza kwenye bandari
-- Unaweza kupeleka bandari nyingi kwa wakati mmoja (inasaidia ikiwa utaongeza hifadhidata baadaye)
+- Codespaces hutambua moja kwa moja wakati programu yako inaanza kusikiliza bandari
+- Unaweza kupeleka bandari nyingi kwa wakati mmoja (inayosaidia kama utaongeza hifadhidata baadaye)
- Bandari zinabaki kupatikana mradi Codespace yako inaendelea
**Mtiririko wa Kazi wa Maendeleo**:
1. Fanya mabadiliko ya msimbo katika VS Code
-2. FastAPI inajipakia upya kiotomatiki (shukrani kwa hali ya upakiaji upya ya Uvicorn)
+2. FastAPI ina auto-reload (shukrani kwa mode ya reload ya Uvicorn)
3. Jaribu mabadiliko mara moja kupitia URL ya umma
-4. Fanya commit na push unapokuwa tayari
+4. Fanya commit na push ukimaliza
-> 💡 **Kidokezo cha Pro**: Weka alama URL yako ya backend ya Codespace wakati wa maendeleo. Kwa kuwa majina ya Codespace ni thabiti, URL haitabadilika mradi unatumia Codespace ile ile.
+> 💡 **Ushauri Bora**: Weka alama URL ya backend ya Codespace wakati wa maendeleo. Kwa kuwa majina ya Codespace ni thabiti, URL haitabadilika mradi unatumia Codespace ile ile.
-## Kuunda Kiolesura cha Gumzo cha Frontend: Ambapo Binadamu Hukutana na AI
+## Kuunda Uso wa Chat wa Frontend: Hapo Watu Wanakutana na AI
-Sasa tutajenga kiolesura cha mtumiaji – sehemu inayodhibiti jinsi watu wanavyowasiliana na msaidizi wako wa AI. Kama muundo wa kiolesura cha awali cha iPhone, tunazingatia kufanya teknolojia ngumu iwe rahisi na ya asili kutumia.
+Sasa tutaweka muonekano wa mtumiaji – sehemu inayobainisha jinsi watu wanavyowasiliana na msaidizi wako wa AI. Kama muundo wa interface ya iPhone asili, tunalenga kufanya teknolojia tata ionekane rahisi na ya asili kutumia.
-### Kuelewa Usanifu wa Kisasa wa Frontend
+### Kuelewa Mhandisi wa Kisasa wa Frontend
-Kiolesura chetu cha gumzo kitakuwa kile tunachokiita "Single Page Application" au SPA. Badala ya mbinu ya zamani ambapo kila bonyeza inasababisha ukurasa mpya kupakiwa, programu yetu inasasisha kwa urahisi na mara moja:
+Uso wetu wa chat utakuwa kile tunachokiita "Programu ya Ukurasa Mmoja" au SPA. Badala ya mbinu ya zamani ambapo kila kubonyeza kunapakia ukurasa mpya, app yetu husasisha kwa simu na papo hapo:
-**Tovuti za zamani**: Kama kusoma kitabu cha karatasi – unageuza kurasa mpya kabisa
-**Programu yetu ya gumzo**: Kama kutumia simu yako – kila kitu kinatiririka na kusasishwa bila shida
+**Tovuti za zamani**: Kama kusoma kitabu cha karatasi – unageuza kurasa mpya kabisa
+**App yetu ya chat**: Kama kutumia simu yako – kila kitu kinatiririka na kusasishwa bila shida
```mermaid
graph TD
- A[User Types Message] --> B[JavaScript Captures Input]
- B --> C[Validate & Format Data]
- C --> D[Send to Backend API]
- D --> E[Display Loading State]
- E --> F[Receive AI Response]
- F --> G[Update Chat Interface]
- G --> H[Ready for Next Message]
+ A[Mtu Mtumiaji Andika Ujumbe] --> B[JavaScript Inakamata Kuingiza]
+ B --> C[Thibitisha & Panga Data]
+ C --> D[Tuma kwa API ya Backend]
+ D --> E[Onyesha Hali ya Kupakia]
+ E --> F[Pokea Jibu la AI]
+ F --> G[Sabisha Kiolesura cha Mazungumzo]
+ G --> H[Tayari kwa Ujumbe Ufuo]
+```
+```mermaid
+classDiagram
+ class ChatApp {
+ +messages: HTMLElement
+ +form: HTMLElement
+ +input: HTMLElement
+ +sendButton: HTMLElement
+ +BASE_URL: string
+ +API_ENDPOINT: string
+
+ +constructor()
+ +initializeEventListeners()
+ +handleSubmit(event)
+ +callAPI(message)
+ +appendMessage(text, role)
+ +escapeHtml(text)
+ +scrollToBottom()
+ +setLoading(isLoading)
+ }
+
+ ChatApp --> DOM : inaendesha
+ ChatApp --> FastAPI : inatuma maombi
```
-
### Nguzo Tatu za Maendeleo ya Frontend
-Kila programu ya frontend – kutoka tovuti rahisi hadi programu ngumu kama Discord au Slack – inajengwa juu ya teknolojia tatu za msingi. Fikiria kama msingi wa kila kitu unachokiona na kuingiliana nacho kwenye wavuti:
+Kila programu ya frontend – kutoka tovuti rahisi hadi app ngumu kama Discord au Slack – imejengwa kwa teknolojia kuu tatu. Fikiri kama msingi wa kila unachoona na kuwasiliana nacho kwenye wavuti:
-**HTML (Muundo)**: Hii ni msingi wako
-- Inaamua ni vipengele gani vinavyokuwepo (vifungo, maeneo ya maandishi, vyombo)
-- Inatoa maana kwa maudhui (hii ni kichwa, hii ni fomu, nk.)
-- Inaunda muundo wa msingi ambao kila kitu kingine kinajengwa juu yake
+**HTML (Muundo)**: Hii ni msingi wako
+- Hutoa maelezo kuhusu vipengele vilivyopo (vitufe, maeneo ya maandishi, chombo)
+- Hutoa maana kwa maudhui (hii ni kichwa, hii ni fomu, n.k.)
+- Hutengeneza muundo wa msingi unaoendeshwa na kila kitu kingine
-**CSS (Uwasilishaji)**: Hii ni mbunifu wako wa ndani
-- Inafanya kila kitu kionekane kizuri (rangi, fonti, mipangilio)
-- Inashughulikia saizi tofauti za skrini (simu vs laptop vs tablet)
-- Inaunda michoro laini na maoni ya kuona
+**CSS (Uwasilishaji)**: Hii ni mbunifu wako wa ndani
+- Inafanya kila kitu kuonekana nzuri (rangi, fonti, upangaji)
+- Inasimamia ukubwa tofauti za skrini (simu vs laptop vs kibao)
+- Hutoa michoro laini na mrejesho wa kuona
-**JavaScript (Tabia)**: Hii ni akili yako
-- Inajibu kile watumiaji wanachofanya (kubofya, kuandika, kusogeza)
-- Inazungumza na backend yako na kusasisha ukurasa
-- Inafanya kila kitu kiwe cha kuingiliana na cha nguvu
+**JavaScript (Tabia)**: Hii ni ubongo wako
+- Inajibu kile watumiaji wanachofanya (kubofya, kuandika, kurusha chini)
+- Inazungumza na backend yako na kusasisha ukurasa
+- Inafanya kila kitu kuwa mwingiliano na nguvu
-**Fikiria kama muundo wa usanifu:**
-- **HTML**: Mchoro wa muundo (kufafanua nafasi na uhusiano)
-- **CSS**: Muundo wa uzuri na mazingira (mtindo wa kuona na uzoefu wa mtumiaji)
+**Fikiri kama usanifu wa usanifu:**
+- **HTML**: Ramani ya muundo (kueleza nafasi na uhusiano)
+- **CSS**: Muundo wa urembo na mazingira (mwelekeo wa kuona na uzoefu wa mtumiaji)
- **JavaScript**: Mifumo ya mitambo (utendaji na mwingiliano)
-### Kwa nini Usanifu wa Kisasa wa JavaScript Unahitajika
+### Kwa Nini Usanifu wa JavaScript wa Kisasa Ni Muhimu
-Programu yetu ya gumzo itatumia mifumo ya kisasa ya JavaScript ambayo utaona katika programu za kitaalamu. Kuelewa dhana hizi kutakusaidia unapokua kama msanidi programu:
+App yetu ya chat itatumia mifumo ya kisasa ya JavaScript ambayo utaiona katika programu za kitaalamu. Kuelewa dhana hizi kutakusaidia unavyoendelea kama mendelezaji:
-**Usanifu wa Msingi wa Darasa**: Tutapanga msimbo wetu katika madarasa, ambayo ni kama kuunda michoro ya vitu
-**Async/Await**: Njia ya kisasa ya kushughulikia shughuli zinazochukua muda (kama simu za API)
-**Programu Inayoendeshwa na Matukio**: Programu yetu inajibu vitendo vya mtumiaji (kubofya, kubonyeza funguo) badala ya kuendesha katika mzunguko
-**Manipulation ya DOM**: Kusasisha maudhui ya ukurasa wa wavuti kwa nguvu kulingana na mwingiliano wa mtumiaji na majibu ya API
+**Usanifu wa Mifumo ya Darasa**: Tutapanga msimbo wetu kwa madarasa, ambayo ni kama kutengeneza ramani za vitu
+**Async/Await**: Njia ya kisasa kushughulikia shughuli zinazochukua muda (kama miito ya API)
+**Programu Iliyotegemea Matukio**: App yetu inajibu hatua za mtumiaji (kama kubofya, kubonyeza vidokezo) badala ya kuendesha kwa mizunguko
+**Udhibiti wa DOM**: Kusasisha mabadiliko ya ukurasa wa wavuti kwa misukumo ya mtumiaji na majibu ya API
-### Usanidi wa Muundo wa Mradi
+### Mpangilio wa Mradi
-Unda saraka ya frontend na muundo huu uliopangwa:
+Unda saraka ya frontend na mpangilio huu uliopangwa:
```text
frontend/
@@ -971,17 +1378,17 @@ frontend/
```
**Kuelewa usanifu:**
-- **Inatenganisha** masuala kati ya muundo (HTML), tabia (JavaScript), na uwasilishaji (CSS)
-- **Inadumisha** muundo rahisi wa faili ambao ni rahisi kuvinjari na kurekebisha
-- **Inafuata** mazoea bora ya maendeleo ya wavuti kwa shirika na usimamizi
+- **Inatenga** masuala kati ya muundo (HTML), tabia (JavaScript), na uwasilishaji (CSS)
+- **Inadumisha** muundo rahisi wa faili unaoweza kutembea na kuhariri kwa urahisi
+- **Inafuata** mbinu bora za maendeleo ya wavuti kwa usimamizi na uendelevu
-### Kujenga Msingi wa HTML: Muundo wa Semantiki kwa Ufikiaji
+### Kujenga Msingi wa HTML: Muundo wa Semantic kwa Upatikanaji
-Hebu tuanze na muundo wa HTML. Maendeleo ya kisasa ya wavuti yanasisitiza "HTML ya semantiki" – kutumia vipengele vya HTML vinavyoelezea waziwazi kusudi lao, si tu muonekano wao. Hii inafanya programu yako ipatikane kwa wasomaji wa skrini, injini za utafutaji, na zana zingine.
+Tuanze na muundo wa HTML. Maendeleo ya wavuti ya kisasa yanasisitiza "HTML semantic" – kutumia vipengele vya HTML vinavyoelezea wazi kusudi lao, si tu muonekano. Hii hufanya programu yako ipatikane kwa wasomaji wa skrini, injini za utafutaji, na zana nyingine.
-**Kwa nini HTML ya semantiki ni muhimu**: Fikiria kuelezea programu yako ya gumzo kwa mtu kupitia simu. Ungeweza kusema "kuna kichwa na kichwa, eneo kuu ambapo mazungumzo yanaonekana, na fomu chini kwa kuandika ujumbe." HTML ya semantiki hutumia vipengele vinavyolingana na maelezo haya ya asili.
+**Kwa nini HTML semantic ni muhimu**: Fikiria unamuambia mtu app yako ya chat kwa simu. Ungesema "kuna kichwa lenye kichwa na maelezo, eneo kuu ambapo mazungumzo yanaonekana, na fomu chini kwa kuandika ujumbe." HTML semantic hutumia vipengele vinavyolingana na maelezo haya ya asili.
-Unda `index.html` na markup hii iliyopangwa kwa uangalifu:
+Tengeneza `index.html` na alama hii iliyoundwa kwa kufikiria:
```html
@@ -1026,74 +1433,73 @@ Unda `index.html` na markup hii iliyopangwa kwa uangalifu:
**Kuelewa kila kipengele cha HTML na kusudi lake:**
#### Muundo wa Hati
-- **``**: Inaambia kivinjari hii ni HTML5 ya kisasa
-- **``**: Inataja lugha ya ukurasa kwa wasomaji wa skrini na zana za tafsiri
-- **``**: Inahakikisha usimbaji sahihi wa herufi kwa maandishi ya kimataifa
-- **``**: Inafanya ukurasa uweze kujibika kwa simu kwa kudhibiti zoom na kiwango
-
-#### Vipengele vya Semantiki
-- **``**: Inatambulisha wazi sehemu ya juu na kichwa na maelezo
-- **``**: Inateua eneo kuu la maudhui (ambapo mazungumzo yanatokea)
-- **`