marian-en-fa

An English → Persian (Farsi) neural machine translation (ترجمهٔ ماشینی) model, based on the MarianMT architecture and trained from scratch (آموزش از صفر) on the OpenSubtitles en-fa parallel corpus. Built specifically to be small and fast enough for real-time, fully offline translation on Android (ترجمهٔ آفلاین و بلادرنگ روی اندروید — بدون نیاز به اینترنت؛ see onnx-int8/ below).

Model details

• Architecture: Marian (Transformer encoder-decoder), 6 encoder layers, 6 decoder layers, 8 attention heads, d_model=512, FFN dim 2048
• Parameters: ~60.65M
• Vocabulary: 32,000 shared subword tokens (SentencePiece Unigram), share_encoder_decoder_embeddings=True
• Max sequence length: 128 tokens
• Training data: OPUS OpenSubtitles en-fa (cleaned, deduplicated, length-ratio filtered — see Data section)
• Training: trained for 3 epochs, then resumed from that checkpoint and continued through a 4th epoch (this repo is the epoch-4 / final model — see marian-en-fa-epoch4 in the training pipeline). Batch size 64 (gradient accumulation 2 → effective batch 128), learning rate 5e-4, 4000 warmup steps, fp16, on a single Colab T4 GPU

Data (داده‌های آموزشی)

Trained on the OPUS OpenSubtitles en-fa corpus . Cleaning steps applied before training:

• Stripped leading dialogue dashes and stray HTML-like tags
• Dropped pairs where the Persian side had no Persian script, or the English side contained Persian script / no Latin characters
• Dropped pairs with an extreme English/Persian length ratio (>3.5 or <0.28), a common signal of misaligned subtitle lines
• Deduplicated exact (en, fa) pairs
• Split into train / 3,000-sentence validation / 3,000-sentence test sets

Usage (PyTorch / transformers)

from transformers import MarianTokenizer, MarianMTModel

tokenizer = MarianTokenizer.from_pretrained("omid1989ahmadi/marian-en-fa")
model = MarianMTModel.from_pretrained("omid1989ahmadi/marian-en-fa")

inputs = tokenizer("Hello, how are you?", return_tensors="pt")
output = model.generate(**inputs, max_length=128, num_beams=4)
print(tokenizer.decode(output[0], skip_special_tokens=True))
# سلام، حالت چطوره؟

A few more example translations from this model:

Test set results

test_100_result.txt is included in the repo — a sample of 100 translation outputs from the model's test split, for a quick look at output quality without having to run inference yourself.

On-device / mobile (ONNX, int8 — کوانتیزه‌شده برای اجرا روی موبایل)

The onnx-int8/ subfolder contains a quantized, mobile-ready export:

Sizes: fp32 ONNX ~630 MB total → int8 ~117 MB total.

CPU benchmark (10 short sentences, ONNX Runtime, CPUExecutionProvider, beam search width 4): average 318 ms, fastest 206 ms, slowest 472 ms.

These files were exported with optimum-cli export onnx --task text2text-generation-with-past and quantized with onnxruntime.quantization.quantize_dynamic. tokenizer_source.json / tokenizer_target.json were built with transformers' internal MarianConverter (Marian has no official *Fast tokenizer, so these are generated directly from the SentencePiece + vocab files rather than saved automatically).

Android / Kotlin

Load with ai.djl.huggingface.tokenizers.HuggingFaceTokenizer (encode with tokenizer_source.json, decode with tokenizer_target.json) and ai.onnxruntime (onnxruntime-android) for the three ONNX graphs, using a two-session KV-cache decoding loop (first step: decoder_model_quantized.onnx; subsequent steps: decoder_with_past_model_quantized.onnx, which does not take encoder_hidden_states as input, only input_ids + encoder_attention_mask + the cached past_key_values.*). Note: the fast tokenizer does not append the end-of-sequence token automatically — append eos_token_id (see config.json) to the encoded input ids yourself.

Limitations

• Trained solely on subtitle dialogue, so it's strongest on conversational, everyday English and may be weaker on formal, technical, or domain-specific text.
• Quality degrades on long, run-on sentences (30+ tokens); this is more noticeable with greedy/on-device decoding than with beam search.
• No context beyond a single sentence — pronouns and references across sentences aren't resolved.
• Sensitive to upstream transcription errors when used in a speech-to-text → translate pipeline (errors are translated as if they were the real input).

Checkpoints

Training checkpoints (checkpoint-<step>/) are included in the repo alongside the final model, for anyone who wants to continue fine-tuning rather than starting from the fully-trained weights. Checkpoints were saved every 5,000 steps (save_steps=5000), with only the 3 most recent kept at any time (save_total_limit=3) — so the checkpoints present are the last few saved during training, not the full training history.

License

MIT. Note that the OpenSubtitles training data itself carries its own OPUS license terms, worth checking before wide redistribution.