African Translate JS - Documentation

📦 Installation

1. Via CDN (Recommended)

<script src="https://your-cdn.com/african-translate.min.js"></script>

2. Via NPM

npm install african-translate-js

3. Download

Download african-translate.js and include it in your project

🚀 Quick Start

Basic Usage

<!-- 1. Include the library -->
<script src="african-translate.js"></script>

<!-- 2. Add data-translate attributes to elements -->
<h1 data-translate="welcome">Welcome</h1>
<p data-translate="hello">Hello</p>
<button data-translate="login">Login</button>

<!-- 3. Initialize the translator -->
<script>
  const translator = new AfricanTranslate({
    language: 'sw', // Swahili
    autoTranslate: true
  });
</script>
            

With Language Switcher

<div id="lang-selector"></div>

<script>
  const translator = new AfricanTranslate({
    language: 'en',
    autoTranslate: true,
    persistLanguage: true
  });
  
  // Create language switcher
  translator.createLanguageSwitcher('lang-selector', {
    className: 'my-language-selector',
    defaultLabel: 'Choose Language'
  });
</script>
            

🗣️ Supported Languages

Swahili (sw) - East Africa 100+ words
Yoruba (yo) - Nigeria, West Africa 100+ words
Zulu (zu) - South Africa 100+ words
Hausa (ha) - Nigeria, Niger, West Africa 100+ words
Igbo (ig) - Nigeria, West Africa 100+ words
Amharic (am) - Ethiopia 100+ words
Afrikaans (af) - South Africa 100+ words
Somali (so) - Somalia, Horn of Africa 100+ words
Shona (sn) - Zimbabwe 100+ words
Xhosa (xh) - South Africa 100+ words

⚡ Advanced Features

1. Custom Translations

const translator = new AfricanTranslate({
  language: 'sw',
  customTranslations: {
    sw: {
      'my-custom-key': 'Tafsiri yangu maalum',
      'app-name': 'Jina la Programu'
    }
  }
});
            

2. Translate Function

// Get translation programmatically
const greeting = translator.t('hello'); // Returns "Halo" in Swahili

// With variable replacement
translator.addLanguage('sw', {
  'greeting': 'Habari {{name}}!'
});
const msg = translator.t('greeting', { name: 'John' }); // "Habari John!"
            

3. Translate Attributes

<input 
  type="text" 
  data-translate-placeholder="search"
  placeholder="Search"
>

<img 
  src="logo.png" 
  data-translate-alt="logo"
  alt="Logo"
>
            

4. Language Detection

const translator = new AfricanTranslate({
  detectLanguage: true, // Auto-detect browser language
  autoTranslate: true
});
            

5. Callbacks

const translator = new AfricanTranslate({
  language: 'sw',
  onLanguageChange: (lang) => {
    console.log('Language changed to:', lang);
    // Update UI, analytics, etc.
  }
});
            

⚙️ Configuration Options

const translator = new AfricanTranslate({
  language: 'sw',              // Initial language (default: 'en')
  autoTranslate: true,         // Auto-translate on init (default: true)
  detectLanguage: false,       // Auto-detect browser language (default: false)
  storageKey: 'app-lang',      // LocalStorage key (default: 'african-translate-lang')
  excludeClasses: ['notranslate'], // Classes to exclude (default: ['notranslate'])
  customTranslations: {},      // Add your own translations
  fallbackLanguage: 'en',      // Fallback if translation missing
  onLanguageChange: null,      // Callback function
  translateAttributes: ['placeholder', 'title', 'alt'], // Attributes to translate
  persistLanguage: true        // Save language preference (default: true)
});
            

📚 API Methods

translate(langCode) - Translate entire page to specified language
t(key, replacements) - Get translation for a specific key
addLanguage(langCode, translations) - Add new language dynamically
getAvailableLanguages() - Get array of available language codes
getCurrentLanguage() - Get current active language
createLanguageSwitcher(containerId, options) - Create UI language selector
reset() - Reset to original language (English)

💡 Real-World Examples

E-commerce Website

<nav>
  <a data-translate="home">Home</a>
  <a data-translate="products">Products</a>
  <a data-translate="contact">Contact</a>
</nav>

<button data-translate="login">Login</button>
<input data-translate-placeholder="search" placeholder="Search">
            

Dashboard Application

<aside>
  <h3 data-translate="settings">Settings</h3>
  <button data-translate="save">Save</button>
  <button data-translate="cancel">Cancel</button>
  <button data-translate="delete">Delete</button>
</aside>
            

🌐 Browser Support

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)
Opera (latest)
Mobile browsers (iOS Safari, Chrome Mobile)

🤝 Contributing

Want to add more African languages or improve translations? Contributions are welcome!

🌍 African Translate JS

Welcome

Home

Services

Products