JamboScript 🇰🇪

Lugha ya programu kwa Kiswahili — A Swahili programming language that transpiles to JavaScript.

JamboScript is a beginner-friendly programming language designed for native Swahili speakers to learn programming concepts using familiar language constructs. It lowers the cognitive barrier to learning code by expressing core programming ideas in Swahili while compiling to readable JavaScript.

Installation

# Clone the repository
git clone https://github.com/yourusername/jamboscript.git
cd jamboscript

# Install dependencies
npm install

# Build the transpiler
npm run build

Usage

# Transpile a JamboScript file to JavaScript (outputs to stdout)
npx jamboscript hello.jambo

# Run the transpiled code directly
npx jamboscript hello.jambo | node

# Show help
npx jamboscript --help

Language Features

Keywords / Maneno Muhimu

| JamboScript | JavaScript | Maelezo (Description) | |-------------|------------|----------------------| | acha | let | Variable declaration | | thabiti | const | Constant declaration | | kazi | function | Function declaration | | rudisha | return | Return statement | | kama | if | If statement | | la sivyo | else | Else statement | | wakati | while | While loop | | rudia | for | For loop | | chagua | switch | Switch statement | | hali | case | Case clause | | kawaida | default | Default clause | | vunja | break | Break statement | | endelea | continue | Continue statement | | kweli | true | Boolean true | | sivyo | false | Boolean false | | tupu | null | Null value | | andika() | console.log() | Print output |

Operators / Opereta

All JavaScript operators are supported, plus Swahili alternatives for logical operators:

• Arithmetic: +, -, *, /, %
• Comparison: ==, !=, ===, !==, <, >, <=, >=
• Logical: &&, ||, !
• Assignment: =, +=, -=, *=, /=
• Increment/Decrement: ++, --
• Ternary: ? :

Swahili Operators (Kid-Friendly!)

| JamboScript | JavaScript | Maelezo | |-------------|------------|---------| | ni | == | Equals (ni sawa) | | na | && | And (logical and) | | au | || | Or (logical or) | | si | ! | Not (negation) | | chini | < | Less than (chini ya) | | zaidi | > | Greater than (zaidi ya) | | mpaka | <= | Up to / until | | angalau | >= | At least |

# Badala ya: kama (umri >= 18 && ana_kitambulisho)
# Andika: 
kama (umri angalau 18 na ana_kitambulisho) {
  andika("Unaweza kupiga kura!")
}

# Badala ya: kama (alama < 50 || !amefanya_mtihani)
# Andika:
kama (alama chini 50 au si amefanya_mtihani) {
  andika("Hujapita!")
}

# Range check - very readable!
kama (umri angalau 6 na umri mpaka 18) {
  andika("Anaweza kwenda shule!")
}

Comments / Maoni

# Hii ni maoni (This is a comment)

Examples / Mifano

Hello World

andika("Jambo Dunia!")

Output:

Jambo Dunia!

Variables and Functions

# Tangaza vigezo (Declare variables)
acha jina = "Fatma"
thabiti UMRI = 25

# Kazi ya salamu (Greeting function)
kazi salamu(mtu) {
  kama (mtu == "Fatma") {
    andika("Jambo boss! 👑")
  } la sivyo {
    andika("Jambo " + mtu)
  }
}

salamu(jina)

Loops / Mizunguko

# While loop
acha i = 1
wakati (i <= 5) {
  andika(i)
  i++
}

# For loop
rudia (acha j = 0; j < 3; j++) {
  andika("Hesabu: " + j)
}

Switch Statement

acha siku = 3

chagua (siku) {
  hali 1:
    andika("Jumatatu")
    vunja
  hali 2:
    andika("Jumanne")
    vunja
  hali 3:
    andika("Jumatano")
    vunja
  kawaida:
    andika("Siku nyingine")
}

Ternary Operator

acha umri = 20
acha hadhi = umri >= 18 ? "mtu mzima" : "mtoto"
andika(hadhi)  # Output: mtu mzima

Functions with Return

kazi ongeza(a, b) {
  rudisha a + b
}

acha jumla = ongeza(5, 3)
andika(jumla)  # Output: 8

Project Structure

jamboscript/
├── src/
│   ├── ast.ts        # AST node type definitions
│   ├── lexer.ts      # Tokenizer (converts source to tokens)
│   ├── parser.ts     # Parser (converts tokens to AST)
│   ├── generator.ts  # Code generator (converts AST to JavaScript)
│   └── index.ts      # CLI entry point
├── examples/
│   └── hello.jambo   # Example JamboScript program
├── dist/             # Compiled JavaScript (after build)
├── package.json
├── tsconfig.json
└── README.md

How It Works

JamboScript uses a classic three-stage transpiler architecture:

1. Lexer (Tokenizer) — Converts source code into tokens, recognizing Swahili keywords, identifiers (with Unicode support), strings, numbers, and operators.

2. Parser — Converts the token stream into an Abstract Syntax Tree (AST) using recursive descent parsing.

3. Code Generator — Walks the AST and produces readable, well-formatted JavaScript code.

JamboScript Source → Lexer → Tokens → Parser → AST → Generator → JavaScript

Error Messages

Error messages are bilingual (Swahili and English) to help learners understand what went wrong:

Kosa la sintaksia (Syntax error) [mstari 5, nafasi 10]: Tarajia ')' baada ya hali (Expected ')' after condition)

Contributing

Contributions are welcome! This is an educational project, so please keep code:

• Simple and readable
• Well-commented
• Beginner-friendly

License

MIT

Karibu sana! (You're very welcome!) 🎉