Tifinagh Dictionary API

Overview

A REST API for Tifinagh script transliteration and Amazigh dictionary lookup. Built with Bun + Hono.

Supports seamless conversion between Arabic, Latin, and Tifinagh scripts, and dictionary lookup with Arabic, English, and Tamazight translations. Powers the /tifinagh commands in Omnibot.

Features

• Transliteration — convert between Arabic, Latin, and Tifinagh scripts via /retype
• Dictionary lookup — search for word meanings across Arabic, English, and Tamazight via /translate
• Auto-detection — automatically detects input script when not specified
• Fuzzy search — matches exact, prefix, and contains queries, ordered by relevance
• No French — per project policy, French is never loaded, stored, or displayed

API Endpoints

POST /retype

Convert text between Arabic, Latin, and Tifinagh scripts.

Field	Type	Required	Description
text	string	yes	The text to convert
from	string	no	Source script (arabic, latin, tifinagh) — auto-detected
to	string	no	Target script (arabic, latin, tifinagh) — auto-detected

Arabic ↔ Latin conversion chains through Tifinagh as an intermediate step.

POST /translate

Look up a word in the Amazigh dictionary.

Field	Type	Required	Description
text	string	yes	The word to look up
from	string	no	Source language (arabic, english, tifinagh, or auto)

Returns results ordered by match quality (exact → prefix → contains), max 10 results.

GET /help

Returns JSON description of all available endpoints with examples.

Tech Stack

Technology	Purpose
Bun	JavaScript runtime
Hono	HTTP framework
abjad-convert	Arabic ↔ Tifinagh transliteration
tamazight	Latin ↔ Tifinagh transliteration
Hugging Face Datasets	Dictionary data sources

Project Structure

src/
├── index.ts          # Hono app — routes, CORS, server
├── retype.ts         # Script transliteration engine
├── translate.ts      # (unused)
└── dictionary.ts     # Dataset loader + in-memory search indexes

scripts/
└── download-dataset.ts   # Fetches and merges datasets from Hugging Face

data/
└── dictionary.json       # Generated by download script (gitignored)

Architecture

The dictionary is loaded into memory at startup with three search indexes (byAmazigh, byArabic, byEnglish). The transliteration engine chains through Tifinagh for Arabic ↔ Latin conversions since no direct converter exists.

Client → Hono App (index.ts) → /help, /retype (retype.ts), /translate (dictionary.ts)

Dataset Sources

• amawal-dataset (CC-BY-4.0) — 15K Amazigh words with Arabic translations and Latin pronunciation
• ircam-dglai-dataset — 17K entries from IRCAM DGLAi dictionary with Arabic and English translations (AI-augmented)

Entries without Arabic or English are excluded. The dataset is not tracked in git.

Quick Start

git clone https://github.com/phaylali/omniversify-tifinagh-dictionary-api.git
cd omniversify-tifinagh-dictionary-api
bun install
bun run download-dataset
bun run start

Server starts on http://localhost:3001. Dataset must be downloaded before /translate works.

Related

Powers the /tifinagh and /quiz commands in Omnibot.