nigeria-translator/README.md

A lightweight and developer-friendly Node.js + TypeScript package for translating between English and major Nigerian languages — Igbo, Yoruba, and Hausa. Provides simple bidirectional translation functions (English ↔ Igbo, Yoruba, Hausa) powered by the Bi

# 🇳🇬 nigeria-translator

![npm version](https://img.shields.io/npm/v/nigeria-translator.svg)
![license](https://img.shields.io/npm/l/nigeria-translator.svg)
![types](https://img.shields.io/badge/TypeScript-Ready-blue.svg)
![downloads](https://img.shields.io/npm/dw/nigeria-translator.svg)

A lightweight, developer-friendly TypeScript package for translating between English and major Nigerian languages (Igbo, Yoruba, and Hausa). 
Perfect for chatbots, APIs, learning apps, and automation workflows.

**Created with ❤️ by [Achu-ulim Agbama](https://github.com/Achufam24)**

---

## ✨ Features

- 🔄 **Bidirectional translation** — English ↔ Igbo/Yoruba/Hausa
- 📘 **Full TypeScript support** with type definitions
- ⚡ **Zero configuration** — works out of the box
- 🪶 **Lightweight** with minimal dependencies
- 🔁 **Promise-based async API** for modern workflows

---

## 📦 Installation

```bash
npm install nigeria-translator
```

```bash
# Or with yarn
yarn add nigeria-translator
```

```bash
# Or with pnpm
pnpm add nigeria-translator
```

---

## 🚀 Quick Start

```javascript
const { englishToIgbo, igboToEnglish } = require('nigeria-translator');

async function translate() {
  const igbo = await englishToIgbo('Hello');
  console.log(igbo); // Output: Ndewo
  
  const english = await igboToEnglish('Ndewo');
  console.log(english); // Output: Hello
}

translate();
```

---

## 📖 Usage

### JavaScript (CommonJS)

```javascript
const {
  englishToIgbo,
  englishToYoruba,
  englishToHausa,
  igboToEnglish,
  yorubaToEnglish,
  hausaToEnglish
} = require('nigeria-translator');

async function examples() {
  // English to Nigerian languages
  console.log(await englishToIgbo('come'));        // → bia
  console.log(await englishToYoruba('how are you')); // → bawo ni
  console.log(await englishToHausa('food'));       // → abinci

  // Nigerian languages to English
  console.log(await igboToEnglish('bia'));         // → come
  console.log(await yorubaToEnglish('bawo ni'));   // → how are you
  console.log(await hausaToEnglish('abinci'));     // → food
}

examples();
```

### TypeScript (ES Modules)

```typescript
import {
  englishToIgbo,
  englishToYoruba,
  englishToHausa,
  igboToEnglish,
  yorubaToEnglish,
  hausaToEnglish
} from 'nigeria-translator';

async function main(): Promise<void> {
  const igbo = await englishToIgbo('friend');
  const yoruba = await englishToYoruba('house');
  const hausa = await englishToHausa('water');

  console.log(igbo);   // → enyi
  console.log(yoruba); // → ile
  console.log(hausa);  // → ruwa

  const translation = await igboToEnglish('anyị');
  console.log(translation); // → we/us
}

main();
```

### Express.js API

```javascript
import express from 'express';
import { englishToYoruba } from 'nigeria-translator';

const app = express();

app.get('/translate', async (req, res) => {
  try {
    const { text } = req.query;
    const translated = await englishToYoruba(text);
    res.json({ original: text, translated });
  } catch (error) {
    res.status(500).json({ error: 'Translation failed' });
  }
});

app.listen(3000, () => {
  console.log('🚀 Translation API running on http://localhost:3000');
});
```

### NestJS Service

```typescript
// translate.service.ts
import { Injectable } from '@nestjs/common';
import {
  englishToIgbo,
  englishToYoruba,
  englishToHausa
} from 'nigeria-translator';

@Injectable()
export class TranslateService {
  async translateToIgbo(text: string): Promise<string> {
    return englishToIgbo(text);
  }

  async translateToYoruba(text: string): Promise<string> {
    return englishToYoruba(text);
  }

  async translateToHausa(text: string): Promise<string> {
    return englishToHausa(text);
  }
}
```

---

## 📚 API Reference

### English → Nigerian Languages

| Function | Description | Returns |
|----------|-------------|---------|
| `englishToIgbo(text: string)` | Translate English to Igbo | `Promise<string>` |
| `englishToYoruba(text: string)` | Translate English to Yoruba | `Promise<string>` |
| `englishToHausa(text: string)` | Translate English to Hausa | `Promise<string>` |

### Nigerian Languages → English

| Function | Description | Returns |
|----------|-------------|---------|
| `igboToEnglish(text: string)` | Translate Igbo to English | `Promise<string>` |
| `yorubaToEnglish(text: string)` | Translate Yoruba to English | `Promise<string>` |
| `hausaToEnglish(text: string)` | Translate Hausa to English | `Promise<string>` |

**Note:** All functions are async and return Promises. Use `await` or `.then()` to handle the results.

---

## 🛠️ Use Cases

- **Chatbots** — WhatsApp, Telegram, Discord bots with Nigerian language support
- **APIs** — Add translation endpoints to your REST or GraphQL APIs
- **Learning Apps** — Build language learning tools for Nigerian languages
- **Content Localization** — Translate UI strings, notifications, and content
- **AI Assistants** — Enhance voice and text assistants with local language support

---

## 🤝 Contributing

Contributions are welcome! If you'd like to improve this package:

1. Fork the repository
2. Create a 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

---

## 👨‍💻 Author

**Achu-ulim Agbama**  
Software Engineer @ Nugitech  
Made with passion for Nigerian culture and accessibility 🇳🇬

- GitHub: https://github.com/Achufam24
- Twitter: https://x.com/agbama_achu

---

## 📄 License

[ISC License](LICENSE) — Free for personal and commercial use.

---

## 🌟 Show Your Support

If this package helped you, please give it a ⭐ on [GitHub](https://github.com/Achufam24/nigeria-translator)!