afro-locale 0.1.0

package/API.md

@@ -0,0 +1,390 @@
+# API Reference
+
+Complete API reference for `@koadit/afro-locale`.
+
+## Table of Contents
+
+- [Classes](#classes)
+- [Interfaces](#interfaces)
+- [Enums & Constants](#enums--constants)
+- [Singleton Instance](#singleton-instance)
+- [Usage Patterns](#usage-patterns)
+
+## Classes
+
+### AfroLocale
+
+Main class for handling localization.
+
+```typescript
+export class AfroLocale {
+  constructor();
+  
+  // Locale Management
+  set(locale: string): void;
+  get(): string;
+  detectLocale(): string;
+  isLocaleSupported(locale: string): boolean;
+  
+  // Formatting
+  formatCurrency(amount: number, currency: string): string;
+  formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
+  formatDate(date: Date, style?: 'short' | 'long'): string;
+  formatTime(date: Date, style?: 'short' | 'long'): string;
+  formatDateTime(date: Date, style?: 'short' | 'long'): string;
+  
+  // Language Information
+  getLanguageName(code: string): string;
+  getLanguageNativeName(code: string): string;
+  getSupportedLanguages(): LocaleConfig[];
+  getSupportedCurrencies(): string[];
+}
+```
+
+## Interfaces
+
+### LocaleConfig
+
+Configuration object for a supported locale.
+
+```typescript
+export interface LocaleConfig {
+  code: string;          // Language code (e.g., 'yo', 'sw')
+  name: string;          // English language name
+  nativeName: string;    // Language name in native script
+  country?: string;      // ISO 3166-1 alpha-2 country code
+}
+```
+
+**Example:**
+```typescript
+{
+  code: 'yo',
+  name: 'Yoruba',
+  nativeName: 'Yorùbá',
+  country: 'NG'
+}
+```
+
+### CurrencyFormat
+
+Configuration for currency formatting.
+
+```typescript
+export interface CurrencyFormat {
+  symbol: string;                  // Currency symbol
+  position: 'left' | 'right';      // Symbol position relative to amount
+  decimals: number;                 // Number of decimal places
+}
+```
+
+**Example:**
+```typescript
+{
+  symbol: '₦',
+  position: 'left',
+  decimals: 2
+}
+```
+
+## Enums & Constants
+
+### Supported Languages
+
+```typescript
+'am' | 'bn' | 'en' | 'ff' | 'ha' | 'ig' | 'ki' | 'ln' | 'lu' | 
+'mg' | 'ny' | 'om' | 'rw' | 'sn' | 'so' | 'st' | 'sw' | 'ti' | 
+'tn' | 'xh' | 'yo' | 'zu'
+```
+
+### Supported Currencies
+
+```typescript
+'ETB' | 'EUR' | 'GHS' | 'KES' | 'MWK' | 'NGN' | 'RWF' | 
+'TZS' | 'UGX' | 'USD' | 'XAF' | 'XOF' | 'ZAR' | 'ZMW'
+```
+
+### Format Styles
+
+```typescript
+type FormatStyle = 'short' | 'long';
+```
+
+## Singleton Instance
+
+### locale
+
+Pre-created singleton instance ready to use.
+
+```typescript
+export const locale: AfroLocale;
+
+// Usage
+import { locale } from '@koadit/afro-locale';
+locale.set('yo');
+locale.formatCurrency(5000, 'NGN');
+```
+
+### Creating Custom Instances
+
+```typescript
+import AfroLocale from '@koadit/afro-locale';
+
+const locale1 = new AfroLocale();
+const locale2 = new AfroLocale();
+
+locale1.set('yo');
+locale2.set('sw');
+
+// Each instance maintains its own state
+```
+
+## Usage Patterns
+
+### Pattern 1: Singleton Pattern
+
+Best for most applications.
+
+```typescript
+import { locale } from '@koadit/afro-locale';
+
+locale.set('yo');
+const formatted = locale.formatCurrency(5000, 'NGN');
+```
+
+### Pattern 2: Instance Pattern
+
+Use when you need to manage multiple independent locales.
+
+```typescript
+import AfroLocale from '@koadit/afro-locale';
+
+const yoruba = new AfroLocale();
+const swahili = new AfroLocale();
+
+yoruba.set('yo');
+swahili.set('sw');
+
+console.log(yoruba.formatCurrency(5000, 'NGN'));
+console.log(swahili.formatCurrency(5000, 'KES'));
+```
+
+### Pattern 3: Factory Pattern
+
+Create a factory for managing locale instances.
+
+```typescript
+import AfroLocale from '@koadit/afro-locale';
+
+class LocaleFactory {
+  private instances: Map<string, AfroLocale> = new Map();
+
+  getLocale(lang: string): AfroLocale {
+    if (!this.instances.has(lang)) {
+      const instance = new AfroLocale();
+      instance.set(lang);
+      this.instances.set(lang, instance);
+    }
+    return this.instances.get(lang)!;
+  }
+}
+
+const factory = new LocaleFactory();
+const yoruba = factory.getLocale('yo');
+```
+
+### Pattern 4: Functional Wrapper
+
+Create helper functions for common operations.
+
+```typescript
+import { locale } from '@koadit/afro-locale';
+
+function formatPrice(price: number, lang: string, currency: string): string {
+  locale.set(lang);
+  return locale.formatCurrency(price, currency);
+}
+
+// Usage
+formatPrice(5000, 'yo', 'NGN');  // ₦5,000.00
+```
+
+### Pattern 5: Locale Provider (React)
+
+Managing locale in React applications.
+
+```typescript
+import React, { createContext, useContext, useState } from 'react';
+import { locale } from '@koadit/afro-locale';
+
+const LocaleContext = createContext<string>('en');
+
+export function LocaleProvider({ children }) {
+  const [currentLocale, setCurrentLocale] = useState('en');
+
+  const handleSetLocale = (newLocale: string) => {
+    locale.set(newLocale);
+    setCurrentLocale(newLocale);
+  };
+
+  return (
+    <LocaleContext.Provider value={currentLocale}>
+      {children}
+    </LocaleContext.Provider>
+  );
+}
+
+export function useLocale() {
+  return useContext(LocaleContext);
+}
+```
+
+### Pattern 6: Vue Composition API
+
+Managing locale in Vue applications.
+
+```typescript
+import { ref, provide, inject } from 'vue';
+import { locale } from '@koadit/afro-locale';
+
+export function useLocale() {
+  const currentLocale = ref('en');
+
+  const setLocale = (newLocale: string) => {
+    locale.set(newLocale);
+    currentLocale.value = newLocale;
+  };
+
+  provide('locale', { currentLocale, setLocale });
+}
+
+export function useCurrentLocale() {
+  return inject('locale');
+}
+```
+
+## Error Handling
+
+### Handling Invalid Locale
+
+```typescript
+const locale = new AfroLocale();
+
+if (locale.isLocaleSupported('xx')) {
+  locale.set('xx');
+} else {
+  console.warn('Locale not supported, using English');
+  locale.set('en');
+}
+```
+
+### Handling Invalid Currency
+
+```typescript
+try {
+  const formatted = locale.formatCurrency(5000, 'INVALID');
+  console.log(formatted); // "INVALID 5000.00"
+} catch (error) {
+  console.error('Currency error:', error);
+}
+```
+
+## Type Safety
+
+### TypeScript
+
+```typescript
+import AfroLocale, { locale, LocaleConfig } from '@koadit/afro-locale';
+
+// Type-safe locale setting
+const supportedLocales: LocaleConfig[] = locale.getSupportedLanguages();
+
+for (const config of supportedLocales) {
+  locale.set(config.code);
+  console.log(`${config.name}: ${config.nativeName}`);
+}
+```
+
+## Performance Considerations
+
+### Caching Formatted Values
+
+```typescript
+const cache = new Map<string, string>();
+
+function getCachedFormatted(
+  amount: number,
+  currency: string,
+  lang: string
+): string {
+  const key = `${amount}-${currency}-${lang}`;
+  
+  if (cache.has(key)) {
+    return cache.get(key)!;
+  }
+  
+  locale.set(lang);
+  const formatted = locale.formatCurrency(amount, currency);
+  cache.set(key, formatted);
+  
+  return formatted;
+}
+```
+
+### Lazy Locale Detection
+
+```typescript
+let detectedLocale: string | null = null;
+
+function getDetectedLocale(): string {
+  if (detectedLocale === null) {
+    detectedLocale = locale.detectLocale();
+  }
+  return detectedLocale;
+}
+```
+
+## Advanced Usage
+
+### Internationalize Custom Objects
+
+```typescript
+interface Product {
+  name: string;
+  price: number;
+  currency: string;
+}
+
+function formatProduct(product: Product, lang: string): string {
+  locale.set(lang);
+  const formatted = locale.formatCurrency(product.price, product.currency);
+  return `${product.name}: ${formatted}`;
+}
+```
+
+### Create Custom Formatter
+
+```typescript
+class CustomFormatter {
+  private locale: AfroLocale;
+
+  constructor(locale: AfroLocale) {
+    this.locale = locale;
+  }
+
+  formatPrice(amount: number, currency: string): string {
+    return `Price: ${this.locale.formatCurrency(amount, currency)}`;
+  }
+
+  formatEvent(date: Date): string {
+    return `Date: ${this.locale.formatDateTime(date)}`;
+  }
+}
+
+const formatter = new CustomFormatter(locale);
+console.log(formatter.formatPrice(5000, 'NGN'));
+```
+
+---
+
+For more examples, see [README.md](README.md) and check the test suite in `src/index.test.ts`.

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-04-09
+
+### Added
+
+- Initial release of `@koadit/afro-locale`
+- Support for 21+ African languages with native names and country codes
+  - West African: Yoruba, Hausa, Igbo, Bambara, Fulfulde
+  - East African: Swahili, Kikuyu, Oromo, Somali, Tigrinya
+  - Southern African: Zulu, Xhosa, Sotho, Tswana, Shona
+  - Central African: Lingala, Luba-Katanga
+  - Other: Amharic, Kinyarwanda, Chichewa, Malagasy, English
+- Support for 14+ African currencies (NGN, KES, ZAR, ETB, UGX, XOF, XAF, etc.)
+- Currency formatting with proper symbols and decimal places
+- Number formatting with locale-specific separators
+- Date and time localization
+- Datetime formatting
+- Automatic locale detection from browser navigator
+- Language information methods (name, native name)
+- Locale validation and normalization
+- Full TypeScript support with interfaces and types
+- ESM and CommonJS module support
+- Comprehensive test suite (28+ test cases)
+- ESLint configuration for code quality
+- Jest configuration for testing
+- Full API documentation in README
+- Contributing guidelines
+- Changelog
+
+### Features
+
+- **Multi-language Support**: 21+ African languages
+- **Currency Formatting**: 14+ African currencies
+- **Date/Time Localization**: Format dates, times, and datetimes
+- **Locale Detection**: Automatic detection from browser
+- **Zero Dependencies**: Built on native Web APIs
+- **Type Safe**: Full TypeScript support
+- **Well Tested**: 28+ unit tests with comprehensive coverage
+- **ESM & CommonJS**: Works with both module systems
+
+### Technical Details
+
+- Built with TypeScript 5.4
+- Jest for unit testing
+- ESLint for code quality
+- Automatic builds for both CJS and ESM
+- Type definitions included
+- Source maps for debugging
+
+## Roadmap
+
+### Planned for Future Releases
+
+- [ ] Additional African languages
+- [ ] Plural form handling
+- [ ] Message translation support (i18n framework)
+- [ ] Relative time formatting (e.g., "2 days ago")
+- [ ] More currency support
+- [ ] React hooks for locale management
+- [ ] Vue composables for locale management
+- [ ] CLI tools for batch translations
+- [ ] Web component for language selector
+- [ ] Locale persistence (localStorage/sessionStorage)
+
+---
+
+For migration information and breaking changes, please refer to the main README.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,96 @@
+# Code of Conduct
+
+## Our Commitment
+
+We are committed to providing a welcoming and inspiring community for all. We expect all members of the community to adhere to this code of conduct in all spaces managed by the afro-locale project, including but not limited to:
+
+- GitHub repositories
+- Issue trackers
+- Pull request discussions
+- Community forums and discussions
+- Social media channels
+- Conferences and meetups
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing opinions, viewpoints, and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+- Encouraging and supporting new contributors
+
+Examples of unacceptable behavior include:
+
+- Harassment, bullying, or threatening language or gestures
+- Discriminatory jokes and language
+- Posting sexually explicit or violent material
+- Posting (or threatening to post) others' personally identifying information ("doxing")
+- Personal attacks or insults
+- Unwelcome sexual attention
+- Advocating for, or encouraging, any of the above behavior
+- Sustained disruption of community spaces
+
+## Scope
+
+This Code of Conduct applies to all community spaces and extends to:
+- Public repositories
+- Private repositories
+- Issues and pull requests
+- Comments and discussions
+- External channels and mailing lists
+- Organizational events and gatherings
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the community team at **conduct@koadit.com**. All complaints will be reviewed and investigated promptly and fairly.
+
+### Reporting
+
+If you are subject to or witness unacceptable behavior, or have any other concerns, please notify us by emailing **conduct@koadit.com** with:
+
+- Your contact information
+- Names (real or usernames) of any individuals involved
+- Description of the incident
+- Context and additional details
+- Any evidence or screenshots
+
+All report contents will be kept confidential and only shared with people who need to know to address the issue.
+
+### Response
+
+Community moderators are obligated to:
+- Maintain confidentiality with respect to the reporter
+- Review and investigate all complaints fairly
+- Take appropriate action in response
+
+### Consequences
+
+Community members who violate this Code of Conduct may face:
+- Warning and removal from community spaces
+- Temporary or permanent ban from community spaces
+- Removal of contributed content
+- Action as determined by community moderators
+
+## Appeals
+
+If you feel a decision was made in error, you may appeal by emailing **conduct-appeal@koadit.com** with:
+- Your appeal details
+- Any additional context
+- Reason why you believe the decision should be reconsidered
+
+## Attribution
+
+This Code of Conduct is adapted from:
+- [Contributor Covenant](https://www.contributor-covenant.org/)
+- [Fedora Community Code of Conduct](https://docs.fedoraproject.org/en-US/fedora/latest/code-of-conduct/)
+
+## Questions?
+
+If you have any questions about this Code of Conduct, please reach out to **conduct@koadit.com**.
+
+---
+
+Thank you for helping create a positive and inclusive community!