Ethio-Intl

๐ŸŒ Ethio-Intl

npm version License: MIT TypeScript npm downloads GitHub stars GitHub issues

A modern JavaScript SDK for Ethiopian web applications with Amharic transliteration, Ethiopian calendar conversion, Geez numerals, and multi-language support.

Project Video

Click the image below to watch our project video:

Watch the video

https://youtube.com/shorts/qNbTvrurcp8?feature=share

๐ŸŽฎ Live Demo

Try the interactive demo: Open Demo

Experience real-time Amharic transliteration, Ethiopian calendar conversion, Geez numerals, and multi-language support!

โœจ Features

๐Ÿš€ Quick Start

Installation

npm install ethio-intl

yarn add ethio-intl

pnpm add ethio-intl

Basic Usage

import { toEthDate, toEthNumber } from 'ethio-intl';

// Ethiopian Calendar
const today = new Date();
const ethDate = toEthDate(today, 'en');
// Result: "Tahsas 13, 2018"

const ethDateAmharic = toEthDate(today, 'am');
// Result: "แ‰ณแˆ…แˆณแˆต 13, 2018"

// Geez Numerals
const geezNumber = toEthNumber(2025);
// Result: "แณแปแณแญ"

const geez100 = toEthNumber(100);
// Result: "แป" (note: no '1' multiplier)

๐Ÿ“š API Reference

Calendar Functions

toEthDate(date, lang?)

Convert Gregorian date to Ethiopian date.

import { toEthDate } from 'ethio-intl';

const ethDate = toEthDate(new Date(2025, 8, 11), 'en');
// Result: "Meskerem 1, 2018"

const ethDateAmharic = toEthDate(new Date(2025, 8, 11), 'am');
// Result: "แˆ˜แˆตแŠจแˆจแˆ 1, 2018"

isEthiopianLeapYear(year)

Check if Ethiopian year is a leap year.

import { isEthiopianLeapYear } from 'ethio-intl';

isEthiopianLeapYear(2018); // true
isEthiopianLeapYear(2017); // false

Numeral Functions

toEthNumber(num)

Convert Arabic number to Geez numerals.

import { toEthNumber } from 'ethio-intl';

toEthNumber(1);      // "แฉ"
toEthNumber(10);     // "แฒ"
toEthNumber(100);    // "แป"
toEthNumber(1000);   // "แฒแป"
toEthNumber(2025);   // "แณแปแณแญ"

fromEthNumber(geezString)

Convert Geez numerals to Arabic number.

import { fromEthNumber } from 'ethio-intl';

fromEthNumber('แณแปแณแญ'); // 2025
fromEthNumber('แป');    // 100

React Integration

EthioProvider

React Context provider for internationalization.

import { EthioProvider } from 'ethio-intl';

const translations = {
  en: { translation: { welcome: 'Welcome!' } },
  am: { translation: { welcome: 'แŠฅแŠ•แŠณแŠ• แ‹ฐแˆ…แŠ“ แˆ˜แŒก!' } }
};

function App() {
  return (
    <EthioProvider
      resources={translations}
      defaultLang="am"
      fallbackLang="en"
    >
      <YourComponents />
    </EthioProvider>
  );
}

useEthioIntl

Custom hook for accessing internationalization context.

import { useEthioIntl } from 'ethio-intl';

function MyComponent() {
  const { t, changeLanguage, currentLang } = useEthioIntl();

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <button onClick={() => changeLanguage('am')}>
        Switch to Amharic
      </button>
    </div>
  );
}

useTransliterate

Hook for real-time Amharic transliteration.

import { useTransliterate } from 'ethio-intl';

function TransliterComponent() {
  const [text, setText] = useState('');
  const translated = useTransliterate(text);

  return (
    <div>
      <input
        value={text}
        onChange={(e) => setText(e.target.value)}
        placeholder="Type in English..."
      />
      <p>Amharic: {translated}</p>
    </div>
  );
}

๐ŸŽฏ Use Cases

Financial Applications

// Ethiopian banking date formatting
const transactionDate = toEthDate(new Date(), 'am');
console.log(`แ‰€แŠ•: ${transactionDate}`);

E-commerce Platforms

// Product pricing in Geez numerals
const price = toEthNumber(2500);
console.log(`แ‹‹แŒ‹: ${price} แ‰ฅแˆญ`);

Cultural Applications

// Traditional date display
const today = new Date();
const ethDate = toEthDate(today, 'am');
const geezYear = toEthNumber(today.getFullYear());

console.log(`แ‹จแŠแŒˆ แ‰€แŠ•: ${ethDate.replace(/\d{4}$/, geezYear)}`);

Government Systems

// Official document dating
const officialDate = toEthDate(new Date(), 'am');
console.log(`แ‰€แŠ•: ${officialDate}`);

๐Ÿ”ง Advanced Configuration

Custom Language Support

const customTranslations = {
  en: {
    translation: { hello: 'Hello' },
    custom: { greeting: 'Welcome' }
  },
  am: {
    translation: { hello: 'แˆฐแˆ‹แˆ' },
    custom: { greeting: 'แŠฅแŠ•แŠณแŠ• แ‹ฐแˆ…แŠ“ แˆ˜แŒก' }
  }
};

<EthioProvider resources={customTranslations}>
  <App />
</EthioProvider>

Dynamic Translation Loading

const { loadNamespace, loadTranslations } = useEthioIntl();

// Load page-specific translations
useEffect(() => {
  loadNamespace('en', 'dashboard', dashboardEn);
  loadNamespace('am', 'dashboard', dashboardAm);
}, []);

๐ŸŒ Supported Languages

Language Code Status
Amharic am โœ… Full Support
English en โœ… Full Support
Tigrinya ti โœ… Full Support
Oromo om โœ… Full Support

๐Ÿ—๏ธ Technical Details

Calendar System

Numeral System

Performance

๐Ÿงช Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

๐Ÿ“ฆ Build

# Development build with watch
npm run dev

# Production build
npm run build

# Type checking
npm run type-check

# Linting
npm run lint

๐Ÿค Contributing

We welcome contributions! Please see our Contributing Guide for details.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

๐Ÿ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

๐Ÿ™ Acknowledgments

๐Ÿ“ž Support

Made with โค๏ธ for the Ethiopian developer community

[๐ŸŒ Website](https://ethio-intl.vercel.app/) โ€ข [๐Ÿ“š Documentation](https://github.com/BeamSol/Ethio-Intl/tree/main/docs) โ€ข [๐ŸŽฎ Demo](https://ethio-intl.github.io/demo) โ€ข [๐Ÿ™ GitHub](https://github.com/BeamSol/Ethio-Intl)
This site is open source. Improve this page.