Grand Diomande Research · Full HTML Reader

NKO-5.3 COMPLETE — PWA + Chrome Extension + Telegram Bot

**Pure client-side transliteration** — works fully offline via a JavaScript port of the Python `nko.transliterate` engine.

Language as Infrastructure proposal experiment writeup candidate score 24 .md

Full Public Reader

NKO-5.3 COMPLETE — PWA + Chrome Extension + Telegram Bot

Status: ✅ COMPLETE
Date: 2025-02-19
Task: Launch web/platform tools using the `nko` Python backend

---

What Was Built

1. Progressive Web App (`web/pwa/`)

Pure client-side transliteration — works fully offline via a JavaScript port of the Python `nko.transliterate` engine.

File	Purpose
`index.html`	Single-page app — dark theme, mobile-responsive
`nko-engine.js`	Pure JS transliteration engine — complete port of Python maps (N'Ko↔IPA↔Latin↔Arabic), longest-match algorithm, script detection
`app.js`	App controller — real-time input handling, copy-to-clipboard, install prompt
`sw.js`	Service worker — offline caching, cache-first strategy
`manifest.json`	PWA manifest — installable on mobile/desktop
`server.py`	Optional FastAPI backend with REST API (transliterate, analyze, proverbs)
`icons/`	SVG + PNG icons (16, 48, 128, 192, 512px)

Features:
- Type in any script → see all 3 (N'Ko, Latin, Arabic) + IPA instantly
- Auto script detection (badge updates live)
- One-click copy per output
- Offline-capable after first load
- Installable as a standalone app
- Optional FastAPI server with 7 API endpoints

Verified: JS engine tested — `salam` → `ߛߊߟߊߡ`, `ߒߞߏ` → `nkɔ`, `hello` → `ߤߍߟߟߋ` ✅

2. Chrome Extension (`web/chrome-extension/`)

Manifest V3 extension with popup, context menus, and inline tooltips.

File	Purpose
`manifest.json`	Manifest V3 — permissions: contextMenus, activeTab, storage
`popup.html/js`	Extension popup — input field, real-time transliteration, click-to-copy
`background.js`	Service worker — context menu creation, keyboard shortcut handler
`content.js`	Content script — selection detection, tooltip rendering
`content.css`	Tooltip styles injected into pages
`nko-engine.js`	Same JS engine (shared with PWA)
`icons/`	16, 48, 128px PNG icons

Features:
- Popup: Type text, see all scripts + IPA, click rows to copy
- Context menu: Select text → right-click → "ߒߞߏ Bridge" → choose N'Ko/Latin/Arabic/All
- Keyboard shortcut: `Alt+N` on selected text → multi-script tooltip
- Tooltips: Results appear as styled floating tooltips near selection
- Persistence: Last input saved to chrome.storage

3. Telegram Bot (`bots/telegram/`)

Full-featured bot using `python-telegram-bot` v22+ with inline mode.

File	Purpose
`bot.py`	Complete bot — 9 commands, inline mode, auto-transliterate
`requirements.txt`	`python-telegram-bot>=21.0`
`.env.example`	Token configuration template

Commands:
| Command | Function |
|---------|----------|
| `/start` | Welcome message with feature overview |
| `/help` | Full command reference |
| `/transliterate <text>` | All 3 scripts + IPA |
| `/nko <text>` | Convert to N'Ko |
| `/latin <text>` | Convert to Latin |
| `/arabic <text>` | Convert to Arabic |
| `/ipa <text>` | IPA with per-character pronunciation guide |
| `/proverb` | Random proverb from 62-entry cultural database |
| `/analyze <text>` | Morphological decomposition (root + affixes + noun class) |

Additional modes:
- Inline: `@nko_bridge_bot salam` → 5 result cards (All, N'Ko, Latin, Arabic, IPA)
- Auto-transliterate: Send any plain text → auto-detect script → full transliteration

---

Shared Architecture

All three tools use the same transliteration approach:

Source Script → IPA (intermediary) → Target Script

PWA & Chrome Extension: `nko-engine.js` — 12KB pure JavaScript, zero dependencies
Telegram Bot & FastAPI: `nko.transliterate` — Python package with full maps
Maps are identical across JS and Python implementations

---

Setup Instructions

PWA (Quickest)

bash

cd Desktop/NKo/web/pwa
python3 -m http.server 8000
# Open http://localhost:8000

PWA + API

bash

cd Desktop/NKo
source .venv/bin/activate
pip install fastapi uvicorn
uvicorn web.pwa.server:app --reload --port 8000

### Chrome Extension
1. Open `chrome://extensions/`
2. Enable Developer mode
3. Click "Load unpacked" → select `web/chrome-extension/`

Telegram Bot

bash

cd Desktop/NKo
source .venv/bin/activate
pip install python-telegram-bot
export BOT_TOKEN=<from-BotFather>
python bots/telegram/bot.py

---

Verification Results

Test	Result
JS engine: `detectScript('ߒߞߏ')`	`nko` ✅
JS engine: `convertAll('salam')`	`{nko: 'ߛߊߟߊߡ', latin: 'salam', arabic: 'سالام'}` ✅
JS engine: `convert('ߒߞߏ', null, 'latin')`	`nkɔ` ✅
Python: `format_all_scripts('hello')`	Full HTML output with all 3 scripts ✅
Python: morphology `mogolu`	`{word_class: 'noun', noun_class: 'person', gloss: 'person-PL'}` ✅
FastAPI: server imports	13 routes registered ✅
Telegram bot: all imports	All command handlers registered ✅

---

File Tree

web/
├── pwa/                    # Progressive Web App
│   ├── index.html
│   ├── nko-engine.js       # Pure JS transliteration engine
│   ├── app.js
│   ├── sw.js               # Service worker
│   ├── manifest.json
│   ├── server.py           # FastAPI backend (optional)
│   ├── requirements.txt
│   ├── README.md
│   └── icons/              # SVG + PNG (16-512px)
│
└── chrome-extension/       # Chrome Extension (Manifest V3)
    ├── manifest.json
    ├── popup.html/js
    ├── background.js
    ├── content.js/css
    ├── nko-engine.js
    ├── README.md
    └── icons/              # PNG (16, 48, 128px)

bots/
└── telegram/               # Telegram Bot
    ├── bot.py              # 9 commands + inline + auto-detect
    ├── requirements.txt
    ├── .env.example
    └── README.md

---

Total new files: 20
JS engine: 12KB, zero deps, fully offline
Python bot: 15KB, uses full `nko` package (transliteration + phonetics + morphology + culture)

Promotion Decision

Attach run IDs, datasets, metrics, and reproduction commands.

Source Anchor

NKo/NKO-5.3-COMPLETE.md

Detected Structure

Method · Evaluation · Code Anchors · Architecture