afro-locale 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,351 @@
+# Contributing to afro-locale
+
+Thank you for your interest in contributing to `@koadit/afro-locale`! We appreciate your help in making this library better for the African developer community.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Making Changes](#making-changes)
+- [Testing](#testing)
+- [Submitting Changes](#submitting-changes)
+- [Style Guide](#style-guide)
+- [Commit Message Guidelines](#commit-message-guidelines)
+
+## Code of Conduct
+
+We are committed to providing a welcoming and inclusive environment for all contributors. Please be respectful and constructive in all interactions.
+
+## Getting Started
+
+1. Fork the repository on GitHub
+2. Clone your fork locally
+3. Create a new branch for your feature or fix
+4. Make your changes
+5. Push your branch to your fork
+6. Submit a pull request
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js 14.0 or higher
+- npm 6.0 or higher (or yarn/pnpm)
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/oluokunkabiru/afro-locale.git
+cd afro-locale
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+```
+
+### Available Commands
+
+```bash
+# Build for both CJS and ESM
+npm run build
+
+# Build CommonJS only
+npm run build:cjs
+
+# Build ESM only
+npm run build:esm
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run linting
+npm run lint
+
+# Type check
+npm run type-check
+```
+
+## Making Changes
+
+### Branch Naming Convention
+
+Use descriptive branch names:
+- `feature/add-new-language` - for new features
+- `fix/currency-formatting` - for bug fixes
+- `docs/update-readme` - for documentation updates
+- `test/improve-coverage` - for test improvements
+
+### File Structure
+
+```
+afro-locale/
+├── src/
+│   ├── index.ts          # Main library code
+│   └── index.test.ts     # Test suite
+├── dist/                 # Built files (auto-generated)
+├── jest.config.js        # Jest configuration
+├── tsconfig.json         # TypeScript configuration
+├── .eslintrc.json        # ESLint configuration
+├── package.json          # Package metadata
+├── README.md             # Documentation
+├── CONTRIBUTING.md       # This file
+└── CHANGELOG.md          # Version history
+```
+
+## Testing
+
+### Writing Tests
+
+Tests are located in `src/index.test.ts`. When adding new features or fixing bugs, please include corresponding tests.
+
+```typescript
+describe('Feature Name', () => {
+  it('should behave correctly', () => {
+    // Arrange
+    const input = ...;
+    
+    // Act
+    const result = ...;
+    
+    // Assert
+    expect(result).toBe(...);
+  });
+});
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm test -- --watch
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run specific test file
+npm test -- src/index.test.ts
+```
+
+### Coverage Requirements
+
+- Aim for at least 80% code coverage
+- All new features should have tests
+- Bug fixes should include regression tests
+
+## Submitting Changes
+
+### Before You Submit
+
+1. Ensure all tests pass: `npm test`
+2. Run linting: `npm run lint`
+3. Run type checking: `npm run type-check`
+4. Update the README if necessary
+5. Add an entry to CHANGELOG.md
+
+### Creating a Pull Request
+
+1. Push your branch to your fork
+2. Navigate to the original repository
+3. Click "New Pull Request"
+4. Fill in the PR template with:
+   - Clear title describing the change
+   - Description of what changed and why
+   - Related issue numbers (if applicable)
+   - Checklist of changes
+
+### PR Template
+
+```markdown
+## Description
+Brief description of the changes
+
+## Related Issues
+Closes #123
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] Performance improvement
+
+## Testing
+- [ ] Added tests for new functionality
+- [ ] All tests pass
+- [ ] Code covered by tests
+
+## Checklist
+- [ ] My code follows the style guidelines
+- [ ] I have updated documentation
+- [ ] I have added tests for my changes
+- [ ] My changes generate no new warnings
+- [ ] I have updated the CHANGELOG.md
+```
+
+## Style Guide
+
+### TypeScript
+
+- Use TypeScript strict mode
+- Add JSDoc comments for public APIs
+- Use meaningful variable and function names
+- Keep functions small and focused
+- Prefer interfaces over type aliases for public APIs
+
+```typescript
+/**
+ * Format a number according to locale conventions
+ * @param value - The number to format
+ * @param options - Optional formatting options
+ * @returns Formatted number string
+ */
+public formatNumber(value: number, options?: Intl.NumberFormatOptions): string {
+  // Implementation
+}
+```
+
+### Code Quality
+
+- Use `const` by default, `let` if reassignment is needed
+- Avoid `var`
+- Avoid `any` types - prefer specific types or generics
+- Keep lines under 100 characters when possible
+- Use meaningful comments for complex logic
+
+### Imports
+
+```typescript
+// Group imports logically
+import type { TypeA, TypeB } from './types';
+import { functionA, functionB } from './utils';
+```
+
+## Commit Message Guidelines
+
+Follow the Conventional Commits specification:
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Type
+
+- `feat`: A new feature
+- `fix`: A bug fix
+- `docs`: Documentation only changes
+- `style`: Changes that don't affect code meaning (formatting, semicolons, etc.)
+- `refactor`: Code change that neither fixes a bug nor adds a feature
+- `perf`: Code change that improves performance
+- `test`: Adding missing tests or correcting existing tests
+- `chore`: Changes to build process, dependencies, etc.
+
+### Scope
+
+Optional - the section of the codebase affected (e.g., `currency`, `locale`, `formatting`)
+
+### Subject
+
+- Use imperative, present tense: "add" not "added" or "adds"
+- Don't capitalize first letter
+- No period (.) at the end
+- Limit to 50 characters
+
+### Body
+
+- Explain what and why, not how
+- Wrap at 72 characters
+- Separate from subject with a blank line
+
+### Footer
+
+- Reference issues: `Closes #123`, `Fixes #456`
+- Note breaking changes: `BREAKING CHANGE: description`
+
+### Examples
+
+```
+feat(currency): add support for XOF currency
+
+Add West African CFA franc (XOF) to supported currencies.
+Includes proper formatting with correct decimal places.
+
+Closes #42
+```
+
+```
+fix(locale): fix locale normalization for en-US
+
+Previously, setting locale to en-US was not properly
+normalized to en. This is now fixed.
+
+Fixes #38
+```
+
+## Adding Support for New Languages
+
+To add support for a new language:
+
+1. Update the `languages` map in `src/index.ts`
+2. Add test cases in `src/index.test.ts`
+3. Update the README.md with the new language
+4. Update CHANGELOG.md
+5. Submit a PR with these changes
+
+Example:
+
+```typescript
+private languages: Record<string, LocaleConfig> = {
+  // ... existing languages
+  xx: { code: 'xx', name: 'Language Name', nativeName: 'Native Name', country: 'XX' },
+};
+```
+
+## Adding Support for New Currencies
+
+To add support for a new currency:
+
+1. Update the `currencyFormats` map in `src/index.ts`
+2. Add test cases in `src/index.test.ts`
+3. Update the README.md with the new currency
+4. Update CHANGELOG.md
+5. Submit a PR with these changes
+
+Example:
+
+```typescript
+private currencyFormats: Record<string, CurrencyFormat> = {
+  // ... existing currencies
+  XXX: { symbol: 'ₓ', position: 'left', decimals: 2 },
+};
+```
+
+## Questions?
+
+- Open an issue on GitHub for bugs and features
+- Start a discussion for questions and ideas
+- Email: support@koadit.com
+
+## Recognition
+
+Contributors will be recognized in:
+- CHANGELOG.md
+- GitHub contributors page
+- Project documentation
+
+Thank you for contributing to make afro-locale better! 🚀

package/EXAMPLES.md

@@ -0,0 +1,327 @@
+# Examples
+
+This directory contains practical examples of using `@koadit/afro-locale`.
+
+## Basic Usage
+
+### CommonJS Example
+
+```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
+
+// Get language info
+console.log(locale.getLanguageName('yo')); // "Yoruba"
+console.log(locale.getLanguageNativeName('yo')); // "Yorùbá"
+```
+
+### ES Module Example
+
+```javascript
+import { locale } from '@koadit/afro-locale';
+
+locale.set('sw');
+console.log(locale.formatCurrency(1000, 'KES'));
+// Output: KSh1,000.00
+```
+
+## E-Commerce Example
+
+```javascript
+import { locale } from '@koadit/afro-locale';
+
+class ProductFormatter {
+  constructor(userLanguage, userCountry) {
+    this.userLanguage = userLanguage;
+    this.userCountry = userCountry;
+    locale.set(userLanguage);
+  }
+
+  formatPrice(price, currency) {
+    return locale.formatCurrency(price, currency);
+  }
+
+  formatAvailableDate(date) {
+    return locale.formatDate(date, 'long');
+  }
+
+  getLanguageDisplay() {
+    const name = locale.getLanguageName(this.userLanguage);
+    const native = locale.getLanguageNativeName(this.userLanguage);
+    return `${name} (${native})`;
+  }
+}
+
+// Usage
+const formatter = new ProductFormatter('yo', 'NG');
+console.log(formatter.formatPrice(5000, 'NGN')); // ₦5,000.00
+console.log(formatter.getLanguageDisplay()); // Yoruba (Yorùbá)
+```
+
+## Multi-Language Support
+
+```javascript
+import { locale } from '@koadit/afro-locale';
+
+const priceInUSD = 50;
+const countries = {
+  'Nigeria': { lang: 'yo', currency: 'NGN', rate: 412 },
+  'Kenya': { lang: 'sw', currency: 'KES', rate: 139 },
+  'South Africa': { lang: 'zu', currency: 'ZAR', rate: 18.5 },
+};
+
+console.log('Prices in different markets:');
+for (const [country, { lang, currency, rate }] of Object.entries(countries)) {
+  locale.set(lang);
+  const localPrice = priceInUSD * rate;
+  const formatted = locale.formatCurrency(localPrice, currency);
+  const langName = locale.getLanguageNativeName(lang);
+  console.log(`${country} (${langName}): ${formatted}`);
+}
+```
+
+## React Example
+
+```jsx
+import React, { useState, useMemo } from 'react';
+import { locale } from '@koadit/afro-locale';
+
+function LanguageSelector() {
+  const [currentLang, setCurrentLang] = useState('en');
+  const languages = useMemo(() => locale.getSupportedLanguages(), []);
+
+  const handleLanguageChange = (event) => {
+    const newLang = event.target.value;
+    locale.set(newLang);
+    setCurrentLang(newLang);
+  };
+
+  return (
+    <select value={currentLang} onChange={handleLanguageChange}>
+      {languages.map(lang => (
+        <option key={lang.code} value={lang.code}>
+          {lang.nativeName}
+        </option>
+      ))}
+    </select>
+  );
+}
+
+function PriceDisplay({ amount, currency }) {
+  const formatted = useMemo(
+    () => locale.formatCurrency(amount, currency),
+    [amount, currency]
+  );
+
+  return <span>{formatted}</span>;
+}
+
+export default function App() {
+  return (
+    <div>
+      <LanguageSelector />
+      <PriceDisplay amount={5000} currency="NGN" />
+    </div>
+  );
+}
+```
+
+## Vue Example
+
+```vue
+<template>
+  <div>
+    <select v-model="currentLang" @change="setLanguage">
+      <option v-for="lang in languages" :key="lang.code" :value="lang.code">
+        {{ lang.nativeName }}
+      </option>
+    </select>
+    <p>Price: {{ formatPrice(5000, 'NGN') }}</p>
+  </div>
+</template>
+
+<script>
+import { ref, computed } from 'vue';
+import { locale } from '@koadit/afro-locale';
+
+export default {
+  name: 'LanguageExample',
+  setup() {
+    const currentLang = ref('en');
+    const languages = computed(() => locale.getSupportedLanguages());
+
+    const setLanguage = (lang) => {
+      locale.set(lang);
+    };
+
+    const formatPrice = (amount, currency) => {
+      return locale.formatCurrency(amount, currency);
+    };
+
+    return {
+      currentLang,
+      languages,
+      setLanguage,
+      formatPrice,
+    };
+  },
+};
+</script>
+```
+
+## TypeScript Example
+
+```typescript
+import AfroLocale, { locale, LocaleConfig } from '@koadit/afro-locale';
+
+class LocalizationService {
+  private locale: AfroLocale;
+
+  constructor() {
+    this.locale = new AfroLocale();
+  }
+
+  setLanguage(code: string): boolean {
+    if (this.locale.isLocaleSupported(code)) {
+      this.locale.set(code);
+      return true;
+    }
+    return false;
+  }
+
+  formatPrice(amount: number, currency: string): string {
+    return this.locale.formatCurrency(amount, currency);
+  }
+
+  formatEventDate(date: Date): string {
+    return this.locale.formatDateTime(date, 'long');
+  }
+
+  getAvailableLanguages(): LocaleConfig[] {
+    return this.locale.getSupportedLanguages();
+  }
+}
+
+const service = new LocalizationService();
+service.setLanguage('sw');
+console.log(service.formatPrice(1000, 'KES')); // KSh1,000.00
+```
+
+## Form Localization Example
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Form Localization Example</title>
+</head>
+<body>
+  <form id="pricing-form">
+    <label>
+      Language:
+      <select id="language">
+        <option value="en">English</option>
+        <option value="yo">Yoruba</option>
+        <option value="sw">Swahili</option>
+      </select>
+    </label>
+
+    <label>
+      Amount:
+      <input type="number" id="amount" value="5000" />
+    </label>
+
+    <label>
+      Currency:
+      <select id="currency">
+        <option value="NGN">NGN</option>
+        <option value="KES">KES</option>
+        <option value="ZAR">ZAR</option>
+      </select>
+    </label>
+
+    <output id="result"></output>
+  </form>
+
+  <script type="module">
+    import { locale } from '@koadit/afro-locale';
+
+    const form = document.getElementById('pricing-form');
+    const languageSelect = document.getElementById('language');
+    const amountInput = document.getElementById('amount');
+    const currencySelect = document.getElementById('currency');
+    const result = document.getElementById('result');
+
+    function updateResult() {
+      const lang = languageSelect.value;
+      const amount = parseInt(amountInput.value) || 0;
+      const currency = currencySelect.value;
+
+      locale.set(lang);
+      const formatted = locale.formatCurrency(amount, currency);
+      result.textContent = formatted;
+    }
+
+    form.addEventListener('change', updateResult);
+    form.addEventListener('input', updateResult);
+
+    updateResult();
+  </script>
+</body>
+</html>
+```
+
+## API Integration Example
+
+```javascript
+import { locale } from '@koadit/afro-locale';
+
+class APIClient {
+  constructor(userLanguage = 'en') {
+    locale.set(userLanguage);
+    this.userLanguage = userLanguage;
+  }
+
+  async getProductPrice(productId) {
+    const response = await fetch(`/api/products/${productId}`);
+    const data = await response.json();
+    
+    // Format price based on user locale
+    const currency = this.getCurrencyForLocale();
+    const formatted = locale.formatCurrency(data.price, currency);
+    
+    return {
+      ...data,
+      formattedPrice: formatted,
+    };
+  }
+
+  getCurrencyForLocale() {
+    const currencyMap = {
+      'yo': 'NGN', // Yoruba
+      'sw': 'KES', // Swahili
+      'zu': 'ZAR', // Zulu
+    };
+    return currencyMap[this.userLanguage] || 'USD';
+  }
+}
+
+// Usage
+const client = new APIClient('yo');
+const product = await client.getProductPrice(123);
+console.log(product.formattedPrice);
+```
+
+---
+
+For more information, see the [README.md](../README.md) and [API.md](../API.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KOADIT Digital Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.