alfredkondoro/directional-hallucinations-african-nmt

# 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 …