alfredkondoro/directional-hallucinations-african-nmt
Domain:
natural language processingRecord type:
datasetsoftware
Creator:
alf
Host:
# Directional Hallucinations in African Neural Machine Translation
Code and data for the paper:
> **Directional Hallucinations in African Neural Machine Translation: How Source Language Typology Shapes Translation Faithfulness**
> Alfred Malengo Kondoro, Chikezie Simon Amalagu, Verrah Akinyi Otiende, Okechukwu God'spraise
> Deep Learning Indaba 2026
## Overview
This repository contains the full pipeline for the direction-controlled evaluation of translation faithfulness across six African target languages using English and Swahili source conditions.
**2 sources × 6 targets × 3 models = 36,000 translations**
## Package Structure
```
directional_hallucinations/
├── config.py # Central configuration
├── requirements.txt
│
├── data/
│ └── load_dataset.py # KKD corpus loading and filtering
│
├── translation/
│ └── nllb_translator.py # NLLB round-trip translation pipeline
│
├── evaluation/
│ ├── loader.py # Load and merge route CSV files
│ ├── validation.py # Output validation and failure flagging
│ └── metrics.py # LaBSE, chrF++, BERTScore computation
│
└── analysis/
└── grouped_summary.py # Aggregation, correlation, human sampling
```
## Setup
```bash
pip install -r requirements.txt
```
Set environment variables before running:
```bash
export GEMINI_API_KEY="your-api-key"
export KKD_DATA_PATH="/path/to/swahili-english.csv"
export TRANSLATIONS_DIR="./roundtrip_translations"
export OUTPUT_DIR="./evaluation_outputs"
```
## Quickstart
### 1. Translate (NLLB)
```python
from data.load_dataset import load_and_filter
from translation.nllb_translator import run_all_jobs
df = load_and_filter()
run_all_jobs(df, output_dir="./roundtrip_translations")
```
### 2. Evaluate
```python
from evaluation.loader import load_all_routes
from evaluation.validation import flag_invalid_rows
from evaluation.metrics import run_all_metrics
from analysis.grouped_summa …