fusha2masry — Modern Standard Arabic → Egyptian Arabic

A fine-tuned UBC-NLP/AraT5v2-base-1024 (~367.5M param Arabic seq2seq T5) that translates Modern Standard Arabic (Fusha) into spoken Cairo Egyptian Arabic (Masry/Aamiya) — the dialect Egyptians actually speak, not the formal written standard.

لقد ذهبت إلى نيويورك . → أنا رحت نيويورك.

Table of contents

• Model details
• License
• Uses
• Bias, risks, and limitations
• Training data
• Training procedure
• Evaluation
• Citation
• Model card contact

Model details

• Model type: Encoder-decoder (seq2seq) Transformer, fine-tuned for sentence-level machine translation
• Language(s): Arabic — Modern Standard Arabic (input) → Egyptian Arabic, Cairo dialect (output)
• License: Research use only (see License below) — not a standard open-source license
• Finetuned from: UBC-NLP/AraT5v2-base-1024
• Developed by: Hassan Abdelshafy
• Repository: github.com/HassanAbdelshafy21/fusha2masry

License

This model is a fine-tune derived from two sources that are each research-use only, not permissively licensed:

• Base model — UBC-NLP/AraT5v2-base-1024 is released by its authors "exclusively for research"; commercial use requires directly contacting the authors (see the AraT5 GitHub repository).
• Training data — the MADAR Corpus (Bouamor et al., LREC 2018) is licensed for research/evaluation use only, non-commercial, with no redistribution of the raw corpus.

As a result, this fine-tuned model is likewise offered for research and non-commercial use only. No commercial-use permission is granted by this repository — if you need to use it commercially, you would need to separately obtain permission from UBC-NLP for the base model and confirm your use complies with MADAR's terms. This repository does not redistribute the MADAR corpus itself, only weights fine-tuned on it, and the model weights are shared here in that spirit — for research and learning, not as an openly-licensed commercial asset.

Uses

Direct use

Sentence-level translation from Modern Standard Arabic into spoken Egyptian Arabic — e.g. translating phrasebook-style, everyday, or travel-related sentences for someone learning the dialect, building an Arabic-dialect-aware chatbot, or localizing MSA content for an Egyptian audience.

from transformers import AutoTokenizer, AutoModelForSeq2SeqLM

tokenizer = AutoTokenizer.from_pretrained("HassanAbdelshafy1/fusha2masry", use_fast=False)
model = AutoModelForSeq2SeqLM.from_pretrained("HassanAbdelshafy1/fusha2masry")

inputs = tokenizer("لقد ذهبت إلى نيويورك .", return_tensors="pt")
outputs = model.generate(**inputs, max_length=96)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))
# -> أنا رحت نيويورك.

Note: load with use_fast=False. The fast (Rust) tokenizer backend has a bug converting this model's legacy SentencePiece vocab format in transformers >= 5.0; the slow (Python) tokenizer loads it correctly.

Out-of-scope use

• Egyptian Arabic → Modern Standard Arabic (the reverse direction). This model only translates Fusha → Masry. Feeding it Egyptian Arabic does not produce MSA — see Bias, risks, and limitations.
• Other Arabic dialects. Trained and evaluated on Cairo Egyptian Arabic specifically; output may not reflect Gulf, Levantine, Maghrebi, or other dialects.
• Non-conversational / legal / medical translation where a mistranslation has real consequences. This is a small research fine-tune on 15k phrasebook-scale examples, not a production-grade translation service.

Bias, risks, and limitations

One-directional only: Fusha → Masry, not the reverse. The model was fine-tuned exclusively on Fusha-input/Masry-output pairs, with no direction indicator in the input. The decoder only ever learned to produce Masry-shaped output, so Egyptian Arabic input is returned nearly unchanged (occasionally with a minor spelling normalization) rather than translated into Fusha. Adding reverse capability would require both reverse-direction training data and an explicit direction tag on the input — without one, similar-looking Fusha/Masry inputs would send contradictory training signal.

Single words and short fragments previously caused hallucination; this was substantially fixed via data augmentation. Earlier versions of this model, fine-tuned only on full BTEC travel-phrasebook sentences, would generate a fluent but entirely unrelated invented sentence when given an isolated word or fragment (e.g. السيارة "the car" → عربيتي اتحركت بسرعة؟ "Did my car move fast?"), because the decoder had never seen a training example where a short input should produce a short output. After adding ~3,600 short-fragment training pairs (see Training data), the same inputs now produce proportionally short, direct translations instead:

Input	Before augmentation	After augmentation
اسمي ("my name")	اسمي عيلتي . (hallucinated: "my name is my family")	اسمي (correct, direct)
لعد تعهدت (fragment)	لو إنت خلصت عدتي، لو سمحت. (unrelated invented sentence)	ما تعهدتش (short, semantically on-target)
هل يمكنني ("can I")	ممكن آخدهم معايا؟ (plausible but invented content)	أقدر (short, direct)

This fix is not perfect or formally guaranteed — validated on a 15-sentence probe with graded-length prefixes, not the full input space — but the qualitative pattern (proportional output length instead of full-sentence hallucination) held consistently across every case tested.

Narrow domain. The core training data is travel/phrasebook style (BTEC), plus a smaller set of synthetic everyday-topic sentences. Idiomatic expressions well outside that combined scope may translate less fluently, even when semantically correct.

Recommendation: treat this as a sentence-level Fusha→Masry translator for phrasebook/everyday content, not a general-purpose or bidirectional translation system. Full methodology and results for all of the above are in the project's REPORT.md.

Training data

Base data: MADAR Corpus (Bouamor et al., LREC 2018), Fusha (MSA) ↔ Cairo Egyptian Arabic parallel sentences, joined by sentID.BTEC, split via MADAR's own split column:

Split	Count
Train	9,000
Validation	1,000
Test	2,000 (also carries Alexandria + Aswan translations as extra references)

Synthetic augmentation: an additional 6,026 Fusha/Masry pairs generated via prompted Gemma 4 (E4B), added to the training split only (validation/test are untouched, pure MADAR):

• ~3,647 fragment pairs — short Fusha fragments (1 word, 2 words, half-sentence) paired with the natural short Masry a speaker would actually say, targeting the hallucination behavior above.
• ~2,379 domain pairs — new full sentences on everyday, non-travel topics (family, work, school, health, home life), targeting the narrow BTEC-domain limitation.

Every synthetic row is tagged source: gemma4_synthetic (vs source: madar) for provenance. This synthetic data is not subject to MADAR's redistribution restriction, since it doesn't reproduce MADAR content.

License note: the MADAR Corpus itself is research/evaluation use only, non-commercial, and may not be redistributed. This repository contains only the fine-tuned model weights, not the underlying corpus — obtain MADAR directly from its authors if you need the data.

Training procedure

Parameter	Value
Base model	UBC-NLP/AraT5v2-base-1024
Training examples	15,026 (9,000 MADAR + 6,026 synthetic)
Epochs	10 (best-BLEU checkpoint kept, not last epoch)
Batch size	32 (train and eval)
Learning rate	3e-4, linear warmup (500 steps) then linear decay
Weight decay	0.01
Precision	bf16
Max sequence length	96 tokens

Full details, including why each value was chosen, in the project's REPORT.md and TRAINING.md.

Evaluation

Testing data: the 2,000-sentence held-out MADAR test split (never seen during training), scored with sacrebleu.

Metrics: BLEU and chrF, both single-reference (Cairo translation only) and multi-reference (Cairo + Alexandria + Aswan alternates) — dialectal translation genuinely has more than one correct answer, so multi-reference scoring avoids penalizing valid alternate phrasings.

Results

Metric	Single-reference	Multi-reference
BLEU	17.33	27.41
chrF	45.94	53.83

Summary: these scores are effectively unchanged from the pre-augmentation model (BLEU 27.17 → 27.41, chrF 53.78 → 53.83) — expected, since this test set is entirely full BTEC-style sentences, which the original 9,000-example training set already covered well. The augmentation's real effect is the fragment-hallucination fix and broader domain coverage described in Bias, risks, and limitations, neither of which this particular test set measures. Full analysis in the project's EVALUATION.md and REPORT.md.

Citation

If you use this model, please cite the underlying data and base model:

@inproceedings{bouamor2018madar,
  title={The MADAR Arabic Dialect Corpus and Lexicon},
  author={Bouamor, Houda and Habash, Nizar and Salameh, Mohammad and Zaghouani, Wajdi and Rambow, Owen and Abdulrahim, Dana and Obeid, Ossama and Khalifa, Salam and Eryani, Fadhl and Erdmann, Alexander and Oflazer, Kemal},
  booktitle={Proceedings of the International Conference on Language Resources and Evaluation (LREC)},
  year={2018}
}

@inproceedings{nagoudi2022arat5,
  title={AraT5: Text-to-Text Transformers for Arabic Language Generation},
  author={Nagoudi, El Moatez Billah and Elmadany, AbdelRahim and Abdul-Mageed, Muhammad},
  booktitle={Proceedings of the 60th Annual Meeting of the Association for Computational Linguistics},
  year={2022}
}

Model card contact

Hassan Abdelshafy — github.com/HassanAbdelshafy21

For questions, issues, or suggestions, please open an issue on the GitHub repository.