afro-locale 0.1.0

package/README.md

@@ -0,0 +1,431 @@
+# afro-locale
+
+[![npm version](https://img.shields.io/npm/v/@koadit/afro-locale.svg)](https://www.npmjs.com/package/@koadit/afro-locale)
+[![npm downloads](https://img.shields.io/npm/dm/@koadit/afro-locale.svg)](https://www.npmjs.com/package/@koadit/afro-locale)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue.svg)](https://www.typescriptlang.org/)
+
+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
+
+```bash
+npm install @koadit/afro-locale
+```
+
+Or with yarn:
+
+```bash
+yarn add @koadit/afro-locale
+```
+
+Or with pnpm:
+
+```bash
+pnpm add @koadit/afro-locale
+```
+
+## 🚀 Quick Start
+
+### CommonJS
+
+```javascript
+const { locale } = require('@koadit/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
+
+```javascript
+import { locale } from '@koadit/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
+
+```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.
+
+```javascript
+locale.set('ha'); // Set to Hausa
+```
+
+#### `get(): string`
+
+Get the currently set locale.
+
+```javascript
+const current = locale.get(); // Returns 'yo', 'en', etc.
+```
+
+#### `detectLocale(): string`
+
+Automatically detect locale from browser navigator (browser only).
+
+```javascript
+const detectedLocale = locale.detectLocale();
+// Returns user's browser language if supported, otherwise English
+```
+
+#### `isLocaleSupported(locale: string): boolean`
+
+Check if a locale is supported.
+
+```javascript
+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.
+
+```javascript
+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.
+
+```javascript
+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.
+
+```javascript
+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.
+
+```javascript
+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.
+
+```javascript
+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.
+
+```javascript
+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).
+
+```javascript
+console.log(locale.getLanguageNativeName('yo'));
+// Output: "Yorùbá"
+
+console.log(locale.getLanguageNativeName('am'));
+// Output: "አማርኛ"
+```
+
+#### `getSupportedLanguages(): LocaleConfig[]`
+
+Get information about all supported languages.
+
+```javascript
+const languages = locale.getSupportedLanguages();
+// Returns array of LocaleConfig objects with code, name, nativeName, country
+```
+
+#### `getSupportedCurrencies(): string[]`
+
+Get list of all supported currency codes.
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+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`:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "module": "esnext",
+    "target": "es2020"
+  }
+}
+```
+
+## 🧪 Testing
+
+Run tests with:
+
+```bash
+npm test
+```
+
+Run tests with coverage:
+
+```bash
+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
+
+```bash
+# Run linting
+npm run lint
+
+# Type check
+npm run type-check
+
+# Full build
+npm run build
+```
+
+## 📜 License
+
+MIT © 2024 [KOADIT Digital Solutions](https://koadit.com)
+
+## 🤝 Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## 📝 Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+## 🐛 Bug Reports & Feature Requests
+
+- [GitHub Issues](https://github.com/oluokunkabiru/afro-locale/issues)
+- [GitHub Discussions](https://github.com/oluokunkabiru/afro-locale/discussions)
+
+## 📖 Resources
+
+- [NPM Package](https://www.npmjs.com/package/@koadit/afro-locale)
+- [GitHub Repository](https://github.com/oluokunkabiru/afro-locale)
+- [KOADIT Digital Solutions](https://koadit.com)
+
+---
+
+**Made with ❤️ for African developers by KOADIT Digital Solutions**

package/SECURITY.md

@@ -0,0 +1,84 @@
+# Security Policy
+
+## Reporting Security Vulnerabilities
+
+If you discover a security vulnerability in `@koadit/afro-locale`, please email **security@koadit.com** instead of using the public issue tracker.
+
+Please include:
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+We will:
+- Acknowledge your report within 48 hours
+- Provide a timeline for addressing the vulnerability
+- Keep you informed of our progress
+- Credit you in the security advisory (unless you prefer anonymity)
+
+## Security Best Practices
+
+### For Users
+
+When using `@koadit/afro-locale`:
+
+1. **Keep Dependencies Updated**: Regularly update to the latest version
+   ```bash
+   npm update @koadit/afro-locale
+   ```
+
+2. **Use HTTPS**: When transmitting localized data over networks, always use HTTPS
+
+3. **Input Validation**: While afro-locale is designed to be safe, always validate user input when possible
+
+4. **Use in Trusted Environments**: The library uses browser APIs (navigator) which should only be used in trusted contexts
+
+### For Contributors
+
+1. **Code Review**: All changes must be reviewed before merging
+2. **Testing**: All changes must include appropriate tests
+3. **Dependencies**: Only add dependencies that are well-maintained and secure
+4. **No Credentials**: Never commit credentials, keys, or sensitive data
+5. **Responsible Disclosure**: Follow our vulnerability reporting process
+
+## Known Limitations
+
+1. **Browser APIs**: Locale detection relies on browser navigator object, which may be restricted in some sandboxed environments
+2. **Intl API**: Relies on the native Intl API, which has varying levels of support across browsers
+3. **No Runtime Validation**: The library does not validate currency amounts or dates at runtime
+
+## Supported Versions
+
+Only the latest major version receives security updates.
+
+| Version | Supported          |
+|---------|-------------------|
+| 1.x     | ✅ Full support   |
+| < 1.0   | ❌ No support     |
+
+## Security Updates
+
+Security updates will be:
+- Released as soon as possible after discovery
+- Included in patch versions
+- Noted in the CHANGELOG.md with a security tag
+- Announced on GitHub
+
+## Dependencies Security
+
+All dependencies are regularly scanned for vulnerabilities using:
+- npm audit
+- Automated dependency scanning
+
+To check security:
+```bash
+npm audit
+```
+
+## License
+
+This policy is available under the MIT License.
+
+---
+
+Thank you for helping keep `@koadit/afro-locale` secure!