Silva3012/xhosa-translator

# Xhosa Translator ## Project Overview The Xhosa Translator is a dedicated neural machine translation system designed for high-quality translation between English and isiXhosa. Built using a production-grade architecture, the project provides a robust foundation for NLP research and practical translation applications, specifically targeting the linguistic nuances of South African languages. This project demonstrates a complete ML lifecycle from dataset preparation to a deployed interface. ## Architecture Overview This project is implemented using **Hexagonal Architecture (Ports and Adapters)**. This design ensures that the core domain logic is decoupled from external technical frameworks, making the system highly testable and maintainable. ### Layers and Roles - **`core/`**: The heart of the application. Contains the pure business logic, domain entities, and abstract Port definitions that define how the application interacts with external services. - **`adapters/`**: Concrete implementations of the Ports. This layer handles dataset preprocessing, model interaction (Helsinki NLP), and the translation service orchestration. - **`ui/`**: The presentation layer. Manages the Gradio-based user interface, including modular layout definitions and custom styling. - **`scripts/`**: Utility layer for operational tasks such as model fine-tuning and performance benchmarking. ### Architecture Diagram ```text +---------------------------------------+ | Adapters Layer | | (Gradio UI, Model Wrapper, Storage) | | | | | +-------------v-------------+ | | | Core Layer | | | | (Translate Use Case, | | | | Domain Logic, Ports) | | | +---------------------------+ | +---------------------------------------+ ``` ## Project Structure The repository is organized following strict separation of concerns: - `core/`: Pure domain logic, domain models, and port interfac …