darija-tools

Small, dependency-free text utilities for Moroccan Darija (الدارجة). The rules and word lists are plain files that can be reviewed and tested.

Install

pip install darija-tools

Python 3.9 or newer is supported.

Use it

from darija_tools import normalize, to_arabic, to_arabizi

normalize("الأَحْمَر")
# 'الاحمر'

to_arabic("3lach bghiti daba")
# 'علاش بغيتي دبا'

to_arabizi("علاش بغيتي دبا")
# '3lach bghiti daba'

to_arabic() checks a curated Darija word list, then uses letter and digraph rules for unknown words. Set keep_loanwords=True to leave recognized French and English loanwords in Latin script:

to_arabic("bghit taxi", keep_loanwords=True)
# 'بغيت taxi'

to_arabizi() uses the same lexicon in reverse and chooses one stable spelling when a word has several valid Arabizi forms. Unknown Arabic words use a readable character mapping.

Command line

darija normalize "الأَحْمَر"
darija translit "3lach bghiti daba"
darija translit --keep-loanwords "bghit taxi"
darija arabizi "علاش بغيتي دبا"

Omit the text argument to read from standard input.

Evaluation

The v0.2 Arabizi-to-Arabic evaluation contains 30 phrases kept outside the unit tests:

• Phrase exact match: 26/30 (86.7%)
• Whitespace-token exact match: 61/66 (92.4%)

The dataset, full error report and evaluation script are checked in. CI regenerates the result and fails if the committed report differs.

This is a small, manually curated regression set, not a blinded study or a claim about all Darija text. The four failed phrases remain visible in the report.

Limits

• Arabizi spelling is not standardized, so transliteration is lossy in both directions.
• Character rules cannot reliably recover unwritten vowels, doubled consonants or word endings.
• Loanword preservation covers a small reviewed list and is opt-in.
• The target is Moroccan Darija; overlap with other Maghrebi dialects is incidental.

Development

python -m pip install -e ".[dev]"
python -m ruff check src tests evaluation
python -m pytest -q
python evaluation/run.py --check
python -m build
python -m twine check dist/*

See CONTRIBUTING.md before changing language rules or data. v0.2 changes are summarized in the release notes.

License

MIT. See LICENSE.