📖 Documentation

🌎 Welcome to YoxOS

YoxOS 1.0 "Ipinlẹ" is the first operating system built with native Yoruba language support from the ground up. Based on Ubuntu 22.04 LTS, it combines the reliability of Linux with comprehensive Yoruba localization and powerful offline AI capabilities.

Key Features at a Glance

🚀 First Boot

When you boot YoxOS for the first time, you will be greeted with the YoxOS Plymouth boot splash followed by the GNOME login screen.

Boot Menu Options

The GRUB boot menu provides 5 options:

Login Credentials

Initial Setup

After logging in, the GNOME Initial Setup wizard may appear. It will guide you through:

1. Language Selection — Yoruba (yo_NG) is pre-selected as the default
2. Keyboard Layout — Yoruba keyboard is already configured
3. Privacy Settings — Configure location and usage data preferences
4. Online Accounts — Optionally connect your accounts (skip if offline)
5. Ready to Use — Start using YoxOS!

🖥 Desktop Overview

YoxOS uses the GNOME desktop environment, fully translated to Yoruba. Here are the key areas of the desktop:

Top Bar

The top bar contains:

• Iṣẹ́ (Activities) — Click to open the Activities overview, search for apps, and switch windows
• Clock & Calendar — Shows current time and date in Yoruba
• System Menu — Network, sound, power, and settings access

Application Menu

Press the Super key (Windows key) or click "Iṣẹ́" to open the Activities overview. From there:

• Type to search for applications in Yoruba or English
• Click the grid icon (☰) to see all installed applications
• All apps show Yoruba names with English descriptions on hover

File Folders

Your home directory folders are in Yoruba:

⌨ Keyboard Input Methods

YoxOS provides three different methods to type Yoruba characters with diacritical marks. Choose the method that works best for you.

Method 1: Character Picker (Recommended)

The Character Picker is a graphical tool that displays all Yoruba characters for easy point-and-click input.

How to Use

1. Open the Character Picker from the app menu (search "Yoruba" or "Character")
2. Click on any Yoruba character to copy it to your clipboard
3. Paste (Ctrl+V) into any application

You can also launch it from the terminal:

yoruba-chars

Method 2: Compose Key

The Compose Key method uses Right Alt as a compose key to create Yoruba characters through key sequences.

How It Works

Press Right Alt, release it, then type a two-key sequence:

Method 3: IBus M17N Engine

IBus with the M17N Yoruba engine provides inline input method support. It integrates with the system input framework for seamless character entry.

Setup

1. Open Ètò (Settings) > Keyboard
2. Click Input Sources > + to add a new source
3. Search for "Yoruba" and select the M17N Yoruba input method
4. Switch between input methods using Super+Space

Usage

When the Yoruba input method is active, type the base letter followed by a modifier key to produce diacritical characters. The IBus popup will show available candidates.

UI Language Settings

YoxOS defaults to Yoruba (yo_NG.UTF-8) for the entire interface. The system translates:

• GNOME Shell menus and panels
• File manager (Nautilus) sidebar and menus
• System Settings panels
• GTK dialog buttons (Open, Save, Cancel, etc.)
• Days of the week and month names
• Application names in the app launcher
• XDG user directory folder names

Where translations are not available, English labels will show as fallback. All application hover tooltips display English descriptions for accessibility.

🤖 AI Assistant

YoxOS includes a powerful AI Assistant with a beautiful GTK3 graphical interface. It provides three AI capabilities — all working completely offline, with no internet connection required.

Launching the AI Assistant

Open the AI Assistant from the application menu by searching for "AI" or "Olùránlọ́wọ́", or run from the terminal:

yoxos-ai

The GUI features three tabs, each providing a different AI capability:

🌎 Translation

The Translation tab uses Meta's NLLB-200 model (No Language Left Behind) to translate between English and Yoruba in both directions.

How to Translate

1. Open the AI Assistant and click the 🌎 Túmò tab
2. Select the translation direction: English → Yoruba or Yoruba → English
3. Type or paste your text in the input area
4. Click Translate — a loading spinner will appear while processing
5. The translation appears in the output area

Translation Tips

• Use simple, clear sentences for best results
• The model handles up to 512 tokens per translation
• First translation may take 10-30 seconds as the model loads into memory
• Subsequent translations are much faster (2-5 seconds)

🔊 Text-to-Speech (Sòrò)

The Text-to-Speech tab converts written Yoruba text into spoken audio using Meta's MMS-TTS model, trained specifically for the Yoruba language.

How to Use TTS

1. Click the 🔊 Sòrò tab in the AI Assistant
2. Type Yoruba text in the input area
3. Click Speak to generate and play the audio

Supported Features

• Natural-sounding Yoruba voice synthesis
• Proper handling of tonal marks and diacriticals
• Audio plays through system speakers automatically
• CPU-only processing (no GPU required)

🎤 Speech-to-Text (Gbọ́)

The Speech-to-Text tab uses OpenAI's Whisper model to transcribe spoken audio into text. It can recognize speech in multiple languages.

How to Use STT

1. Click the 🎤 Gbọ́ tab in the AI Assistant
2. Click Record to start recording from your microphone
3. Speak clearly in Yoruba or English
4. Click Stop to end recording and begin transcription
5. The transcribed text appears in the output area

📦 Applications

YoxOS comes with over 50 pre-installed applications, all with Yoruba names and English hover tooltips. Here are the key applications:

📄 AfrikGPT-Office

AfrikGPT-Office is YoxOS's productivity suite, based on LibreOffice and branded for the African market. It includes five modules with Yoruba menu translations:

📁 File Manager (Àwọn Fáìlì)

The Nautilus file manager is fully translated to Yoruba. Navigation, context menus, and file operations all appear in Yoruba.

Key Navigation

🌐 Web Browser (Aṣàwákírí Firefox)

Firefox is pre-configured with security hardening for safe browsing:

• HTTPS-Only mode enabled by default
• Enhanced Tracking Protection set to Strict
• DNS over HTTPS configured
• Third-party cookies blocked
• Fingerprinting protection enabled

🔒 Security

YoxOS implements an 18-layer defense system, providing enterprise-grade security without the need for a separate antivirus program.

Security Layers

🛡 Firewall

The UFW (Uncomplicated Firewall) is enabled by default with a deny-incoming, allow-outgoing policy.

Common Commands

# Check firewall status
sudo ufw status verbose

# Allow a specific port (e.g., SSH)
sudo ufw allow 22

# Deny a specific port
sudo ufw deny 8080

# Allow an application
sudo ufw allow 'Apache'

🔎 Security Monitor Tool

YoxOS includes a built-in security monitoring tool that provides real-time status of all 18 security layers.

# Check security status
yoxos-security status

# Run a security scan
yoxos-security scan

# Generate a security report
yoxos-security report

🔄 System Updates

YoxOS is configured with automatic security updates through the unattended-upgrades package. Security patches are applied automatically.

Manual Updates

# Update package lists
sudo apt update

# Upgrade installed packages
sudo apt upgrade

# Full system upgrade
sudo apt full-upgrade

# Clean up old packages
sudo apt autoremove

🔧 Troubleshooting

Display Issues

Problem: Black screen or garbled display on boot.

Solution: Select "Safe Graphics Mode" from the GRUB boot menu. This uses the nomodeset kernel parameter for basic graphics.

AI Assistant Slow on First Use

Problem: Translation takes 30+ seconds the first time.

Solution: This is normal. The NLLB-200 model (2.4GB) needs to load into RAM on first use. Subsequent translations will be much faster (2-5 seconds). Ensure you have at least 4GB of available RAM.

No Sound from TTS

Problem: Text-to-speech generates but no audio plays.

Solution:

• Check that PulseAudio is running: pulseaudio --check
• Verify volume is not muted in system settings
• For VMs, ensure audio passthrough is enabled in VM settings

Yoruba Characters Not Displaying

Problem: Yoruba characters show as boxes or question marks.

Solution: Yoruba fonts should be pre-installed. If characters don't render, install additional fonts:

sudo apt install fonts-noto fonts-dejavu fonts-liberation

Cannot Boot from USB

Problem: Computer doesn't boot from USB drive.

Solution:

• Enter BIOS/UEFI setup (usually F2, F12, Del, or Esc at startup)
• Change boot order to prioritize USB devices
• For UEFI systems, disable Secure Boot temporarily if needed
• Ensure the USB was created with a proper tool (Rufus, balenaEtcher, or dd)

AfrikGPT-Office Won't Start

Problem: AfrikGPT-Office crashes with "missing access rights" error.

Solution: Fix file permissions:

# Fix LibreOffice config ownership
sudo chown -R $USER:$USER ~/.config/libreoffice/
# If still failing, reset configuration
rm -rf ~/.config/libreoffice/4/user/
# Then restart AfrikGPT-Office

❔ Frequently Asked Questions

Is YoxOS free?

YoxOS is developed by Dotrous Enterprises LLC. Please check the download page for licensing information.

Does YoxOS need internet to work?

No. YoxOS works fully offline, including all AI features (translation, TTS, STT). Internet is only needed for web browsing, system updates, and online services.

Can I install Windows programs on YoxOS?

YoxOS is a Linux-based OS. While some Windows programs can run via Wine or compatibility layers, it's recommended to use native Linux applications. AfrikGPT-Office provides full compatibility with Microsoft Office file formats.

What file systems does YoxOS support?

YoxOS supports ext4 (default), NTFS (Windows drives), FAT32/exFAT (USB drives), and most standard Linux file systems (XFS, Btrfs, etc.).

How much disk space do the AI models use?

The three AI models total approximately 3GB of disk space:

• NLLB-200 Translation: ~2.4GB
• Whisper STT: ~462MB
• MMS-TTS: ~139MB

Can I dual-boot YoxOS with Windows?

Yes! The Ubiquity installer can detect existing operating systems and set up dual-boot with GRUB automatically. Select "Install alongside Windows" during installation.

Is YoxOS secure enough for business use?

Yes. With 18 security layers including AppArmor, UFW firewall, kernel hardening, and encrypted DNS, YoxOS provides enterprise-grade security suitable for business environments.

How do I switch back to English UI?

Open Settings > Region & Language and change the Language to English. Log out and log back in for changes to take effect. Note: Yoruba keyboard input will remain available regardless of UI language.