Dark Mode

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

BeamSol/Ethio-Intl

Repository files navigation

Ethio-Intl

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:

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

  • Amharic Transliteration: Real-time English to Amharic conversion
  • Ethiopian Calendar: Precise Gregorian - Ethiopian date conversion
  • Geez Numerals: Convert Arabic numbers to traditional Geez script
  • Multi-language Support: Amharic, English, Tigrinya, and Oromo
  • Zero Dependencies: Pure TypeScript with no external libraries
  • TypeScript First: Full type safety and IntelliSense support
  • React Hooks: Custom hooks for easy React integration

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: "taahesaase 13, 2018"

// Geez Numerals
const geezNumber = toEthNumber(2025);
// Result: "20+100+20+5"

const geez100 = toEthNumber(100);
// Result: "100+" (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: "masekarame 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); // "1"
toEthNumber(10); // "10+"
toEthNumber(100); // "100+"
toEthNumber(1000); // "10+100+"
toEthNumber(2025); // "20+100+20+5"

fromEthNumber(geezString)

Convert Geez numerals to Arabic number.

import { fromEthNumber } from 'ethio-intl';

fromEthNumber('20+100+20+5'); // 2025
fromEthNumber('100+'); // 100

React Integration

EthioProvider

React Context provider for internationalization.

); }">import { EthioProvider } from 'ethio-intl';

const translations = {
en: { translation: { welcome: 'Welcome!' } },
am: { translation: { welcome: ''enekwaane dahenaa mathu!' } }
};

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

useEthioIntl

Custom hook for accessing internationalization context.

{t('welcome')}

); }">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.

setText(e.target.value)} placeholder="Type in English..." />

Amharic: {translated}

); }">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(`qane: ${transactionDate}`);

E-commerce Platforms

// Product pricing in Geez numerals
const price = toEthNumber(2500);
console.log(`waagaa: ${price} bere`);

Cultural Applications

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

console.log(`yanaga qane: ${ethDate.replace(/\d{4}$/, geezYear)}`);

Government Systems

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

Advanced Configuration

Custom Language Support

">const customTranslations = {
en: {
translation: { hello: 'Hello' },
custom: { greeting: 'Welcome' }
},
am: {
translation: { hello: 'salaame' },
custom: { greeting: ''enekwaane dahenaa mathu' }
}
};

<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

  • Ethiopian Calendar: 13-month system (12 months x 30 days + Pagume)
  • Leap Years: Ethiopian year % 4 === 3
  • New Year: Meskerem 1 (usually September 11/12)
  • Time Offset: ~7-8 years behind Gregorian

Numeral System

  • Geez Numerals: Unicode-based traditional script
  • Special Rules: No '1' multiplier for 100 (100+) and 10,000 (10,000+)
  • Range: Supports numbers up to 1,000,000+

Performance

  • Bundle Size: ~15KB minified + gzipped
  • Zero Runtime Dependencies: Pure TypeScript implementation
  • Tree Shaking: Import only what you need

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

  • Ethiopian developers community
  • Unicode Consortium for Ethiopic script support
  • Open source contributors

Support

Made with for the Ethiopian developer community

About

Ethio-Intl is an open-source internationalization library built to support Ethiopian languages and systems in modern software development. It brings together: Amharic transliteration , Ethiopian - Gregorian calendar conversion, Geez numeral support, Multi-language foundations (Amharic, Oromo, Tigrinya, English).

Topics

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Stars

Watchers

Forks

Releases

No releases published

Packages

Contributors