afro-locale

A comprehensive internationalization (i18n) library with first-class support for African languages, currencies, and locales. Provides seamless localization for 20+ African languages with native language names, currency formatting, date/time localization, and more.

✨ Features

• 🌍 20+ African Languages - Comprehensive support for major African languages including Yoruba, Hausa, Igbo, Swahili, Zulu, Amharic, and more
• 💱 14+ African Currencies - Built-in formatting for NGN, KES, ZAR, ETB, UGX, XOF, XAF, and other African currencies
• 📅 Date/Time Localization - Format dates, times, and datetimes according to locale-specific conventions
• 🗣️ Native Language Names - Display language names in their native scripts and English equivalents
• 🔢 Number Formatting - Locale-aware number formatting with customizable options
• 📍 Automatic Locale Detection - Detect user's locale from browser navigator
• ⚡ Zero Dependencies - Lightweight library (~7KB minified) built on native Web APIs
• 📦 TypeScript Support - Fully typed for TypeScript projects
• 🎯 ESM & CommonJS - Works with both module systems
• ✅ 100% Test Coverage - Comprehensive test suite with 28+ test cases

📦 Installation

npm install afro-locale

Or with yarn:

yarn add afro-locale

Or with pnpm:

pnpm add afro-locale

🚀 Quick Start

CommonJS

const { locale } = require('afro-locale');

// Set locale
locale.set('yo'); // Yoruba

// Format currency
console.log(locale.formatCurrency(5000, 'NGN'));
// Output: ₦5,000.00

// Format date
console.log(locale.formatDate(new Date(), 'long'));
// Output: 9 Ȁpẹ̀lẹ̀ 2026

ES Modules

import { locale } from 'afro-locale';

// Set locale
locale.set('sw'); // Swahili

// Format number
console.log(locale.formatNumber(1234567));
// Output: 1,234,567

// Format time
console.log(locale.formatTime(new Date(), 'long'));
// Output: 06:18:45

TypeScript

import AfroLocale, { locale, LocaleConfig } from '@koadit/afro-locale';

// Using the singleton instance
locale.set('zu'); // Zulu

// Or create your own instance
const customLocale = new AfroLocale();
customLocale.set('am'); // Amharic

// Get language info
console.log(locale.getLanguageName('zu')); // "Zulu"
console.log(locale.getLanguageNativeName('zu')); // "isiZulu"

📚 API Documentation

Core Methods

set(locale: string): void

Set the active locale for formatting operations.

locale.set('ha'); // Set to Hausa

get(): string

Get the currently set locale.

const current = locale.get(); // Returns 'yo', 'en', etc.

detectLocale(): string

Automatically detect locale from browser navigator (browser only).

const detectedLocale = locale.detectLocale();
// Returns user's browser language if supported, otherwise English

isLocaleSupported(locale: string): boolean

Check if a locale is supported.

if (locale.isLocaleSupported('sw')) {
  locale.set('sw');
}

Formatting Methods

formatCurrency(amount: number, currency: string): string

Format a number as currency with proper symbol and decimal places.

locale.set('en');
console.log(locale.formatCurrency(5000, 'NGN'));
// Output: ₦5,000.00

console.log(locale.formatCurrency(10000, 'KES'));
// Output: KSh10,000.00

console.log(locale.formatCurrency(1000, 'ZAR'));
// Output: R1,000.00

Supported Currencies (14):

• NGN (Nigerian Naira)
• GHS (Ghanaian Cedi)
• KES (Kenyan Shilling)
• ZAR (South African Rand)
• ETB (Ethiopian Birr)
• UGX (Ugandan Shilling)
• TZS (Tanzanian Shilling)
• RWF (Rwandan Franc)
• MWK (Malawian Kwacha)
• ZMW (Zambian Kwacha)
• XOF (West African CFA Franc)
• XAF (Central African CFA Franc)
• USD (US Dollar)
• EUR (Euro)

formatNumber(value: number, options?: Intl.NumberFormatOptions): string

Format a number with locale-specific separators.

locale.set('en');
console.log(locale.formatNumber(1234567));
// Output: 1,234,567

console.log(locale.formatNumber(1234.567, {
  minimumFractionDigits: 2,
  maximumFractionDigits: 2
}));
// Output: 1,234.57

formatDate(date: Date, style?: 'short' | 'long'): string

Format a date according to locale conventions.

const date = new Date(2026, 3, 9);

locale.set('yo');
console.log(locale.formatDate(date, 'long'));
// Output: 9 Ȁpẹ̀lẹ̀ 2026

console.log(locale.formatDate(date, 'short'));
// Output: 09/04/26

formatTime(date: Date, style?: 'short' | 'long'): string

Format a time according to locale conventions.

const date = new Date(2026, 3, 9, 14, 30, 45);

locale.set('en');
console.log(locale.formatTime(date, 'short'));
// Output: 14:30

console.log(locale.formatTime(date, 'long'));
// Output: 14:30:45

formatDateTime(date: Date, style?: 'short' | 'long'): string

Format a complete date and time according to locale conventions.

const date = new Date(2026, 3, 9, 14, 30, 45);

locale.set('en');
console.log(locale.formatDateTime(date, 'long'));
// Output: April 9, 2026, 14:30:45

Language Information Methods

getLanguageName(code: string): string

Get the English name of a language.

console.log(locale.getLanguageName('yo'));
// Output: "Yoruba"

console.log(locale.getLanguageName('sw'));
// Output: "Swahili"

getLanguageNativeName(code: string): string

Get the native name of a language (in its native script).

console.log(locale.getLanguageNativeName('yo'));
// Output: "Yorùbá"

console.log(locale.getLanguageNativeName('am'));
// Output: "አማርኛ"

getSupportedLanguages(): LocaleConfig[]

Get information about all supported languages.

const languages = locale.getSupportedLanguages();
// Returns array of LocaleConfig objects with code, name, nativeName, country

getSupportedCurrencies(): string[]

Get list of all supported currency codes.

const currencies = locale.getSupportedCurrencies();
// Returns: ['NGN', 'GHS', 'KES', 'ZAR', ...]

🌐 Supported Languages (21)

| Code | Language | Native Name | Country | |------|----------|------------|---------| | yo | Yoruba | Yorùbá | NG | | ha | Hausa | Hausa | NG | | ig | Igbo | Igbo | NG | | zu | Zulu | isiZulu | ZA | | sw | Swahili | Kiswahili | KE | | am | Amharic | አማርኛ | ET | | so | Somali | Soomaali | SO | | om | Oromo | Afaan Oromo | ET | | ti | Tigrinya | ትግርኛ | ER | | rw | Kinyarwanda | Kinyarwanda | RW | | bn | Bambara | Bamanankan | ML | | ff | Fulfulde | Fulfulde | SN | | mg | Malagasy | Malagasy | MG | | xh | Xhosa | isiXhosa | ZA | | st | Southern Sotho | Sesotho | ZA | | tn | Tswana | Setswana | BW | | sn | Shona | Shona | ZW | | ny | Chichewa | Chichewa | MW | | ln | Lingala | Lingala | CD | | ki | Kikuyu | Gikuyu | KE | | lu | Luba-Katanga | Luba-Katanga | CD | | en | English | English | GB |

📋 Examples

Multi-Language Support

import { locale } from '@koadit/afro-locale';

const price = 5000;
const currencies = {
  'yo': 'NGN',
  'sw': 'KES',
  'zu': 'ZAR',
};

for (const [lang, currency] of Object.entries(currencies)) {
  locale.set(lang);
  console.log(`${locale.getLanguageName(lang)}: ${locale.formatCurrency(price, currency)}`);
}
// Output:
// Yoruba: ₦5,000.00
// Swahili: KSh5,000.00
// Zulu: R5,000.00

Locale Detection and Fallback

import { locale } from '@koadit/afro-locale';

// Automatically detect user's locale (browser only)
locale.detectLocale();

const supportedLanguages = locale.getSupportedLanguages();
const currentLang = locale.get();

console.log(`Locale set to: ${locale.getLanguageName(currentLang)}`);

E-Commerce Integration

import { locale } from '@koadit/afro-locale';

function formatProductPrice(price, userLanguage, userCountry) {
  locale.set(userLanguage);
  
  const currency = getCurrencyByCountry(userCountry);
  const formatted = locale.formatCurrency(price, currency);
  const nativeLanguage = locale.getLanguageNativeName(userLanguage);
  
  return { formatted, nativeLanguage };
}

🔧 Configuration

TypeScript Configuration

The library includes full TypeScript support. In your tsconfig.json:

{
  "compilerOptions": {
    "strict": true,
    "module": "esnext",
    "target": "es2020"
  }
}

🧪 Testing

Run tests with:

npm test

Run tests with coverage:

npm run test:coverage

The library includes 28+ comprehensive test cases covering:

• Locale management and normalization
• Language support verification
• Currency formatting for all supported currencies
• Number, date, time formatting
• Locale detection
• Type safety

🔍 Quality Assurance

• ESLint: Code quality checks
• TypeScript: Strict type checking
• Jest: 28+ unit tests
• Coverage: Comprehensive test coverage

# Run linting
npm run lint

# Type check
npm run type-check

# Full build
npm run build

📜 License

MIT © 2024 KOADIT Digital Solutions

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📝 Changelog

See CHANGELOG.md for version history.

🐛 Bug Reports & Feature Requests

• GitHub Issues
• GitHub Discussions

📖 Resources

• NPM Package
• GitHub Repository
• KOADIT Digital Solutions

Made with ❤️ for African developers by KOADIT Digital Solutions