README

A Laravel package for transliterating Amharic (Ethiopic) text to Latin and handling phonetically equivalent character variants.

Amharic has several characters that share the same sound — for example አ, ዓ, ኣ, and ዐ are all pronounced the same way. This package maps every character to its Latin phonetic equivalent and provides tools to work with those variants in search, speech recognition, and admin interfaces.

Requirements

• PHP 8.1+
• Laravel 10, 11, or 12

Installation

composer require wossnap/amharic-transliteration

Laravel auto-discovers the service provider. No manual registration needed.

Quick start

use Wossnap\AmharicTransliteration\Facades\AmharicTransliteration;

AmharicTransliteration::transliterate('ሰላም');
// → "selam"

AmharicTransliteration::getAmharicVariants('አምሮ');
// → ["አምሮ", "ኣምሮ", "ዐምሮ", "ዓምሮ"]

You can also inject the service directly:

use Wossnap\AmharicTransliteration\AmharicTransliterationService;

class WordController extends Controller
{
    public function __construct(
        private AmharicTransliterationService $transliterator
    ) {}

    public function store(Request $request)
    {
        $transliterations = $this->transliterator->getSuggestedTransliterations(
            $request->input('word')
        );
    }
}

API reference

Core transliteration

transliterate(string $text): string

Transliterate a full Amharic string to its Latin phonetic equivalent. Non-Amharic characters (spaces, numbers, punctuation) pass through unchanged.

AmharicTransliteration::transliterate('ሰላም');         // "selam"
AmharicTransliteration::transliterate('ደህና ሁን');      // "dehna hun"
AmharicTransliteration::transliterate('hello ሰላም');   // "hello selam"

transliterateChar(string $char): ?string

Transliterate a single character. Returns null if the character has no mapping.

AmharicTransliteration::transliterateChar('ሰ');   // "se"
AmharicTransliteration::transliterateChar('ላ');   // "la"
AmharicTransliteration::transliterateChar('A');   // null
AmharicTransliteration::transliterateChar(' ');   // null

Variant handling

getAmharicVariants(string $word): array

Return every possible Amharic spelling of a word by substituting each character with all of its phonetically equivalent alternatives.

AmharicTransliteration::getAmharicVariants('አምሮ');
// ["አምሮ", "ኣምሮ", "ዐምሮ", "ዓምሮ"]

AmharicTransliteration::getAmharicVariants('ሰላም');
// ["ሰላም", "ሠላም"]

getCharEquivalents(string $char): array

Return all Amharic characters that sound identical to the given character. The given character is always included in the result.

AmharicTransliteration::getCharEquivalents('አ');   // ["አ", "ኣ", "ዐ", "ዓ"]
AmharicTransliteration::getCharEquivalents('ሰ');   // ["ሰ", "ሠ"]
AmharicTransliteration::getCharEquivalents('ለ');   // ["ለ"]  — no equivalents

areEquivalent(string $charA, string $charB): bool

Check whether two characters share the same sound.

AmharicTransliteration::areEquivalent('አ', 'ዓ');   // true
AmharicTransliteration::areEquivalent('አ', 'ዐ');   // true
AmharicTransliteration::areEquivalent('አ', 'ለ');   // false

hasVariants(string $char): bool

Check whether a character has at least one phonetically equivalent alternative.

AmharicTransliteration::hasVariants('አ');   // true
AmharicTransliteration::hasVariants('ለ');   // false

Detection & utility

isAmharic(string $text): bool

Check whether a string contains at least one Amharic character.

AmharicTransliteration::isAmharic('ሰላም');          // true
AmharicTransliteration::isAmharic('hello');         // false
AmharicTransliteration::isAmharic('hello ሰላም');    // true

splitToChars(string $text): array

Split an Amharic (or mixed) string into individual characters using correct multi-byte handling.

AmharicTransliteration::splitToChars('ሰላም');   // ["ሰ", "ላ", "ም"]

Introspection

getMap(): array

Return the full Amharic → Latin character map as an associative array.

$map = AmharicTransliteration::getMap();
$map['ሰ'];   // "se"
$map['ላ'];   // "la"

getEquivalenceGroups(): array

Return all defined equivalence groups. Each entry is an array of characters that share the same sound.

$groups = AmharicTransliteration::getEquivalenceGroups();
// [
//   ["አ", "ኣ", "ዐ", "ዓ"],
//   ["ሀ", "ሐ", "ኀ"],
//   ["ሰ", "ሠ"],
//   ...
// ]

Equivalence groups explained

Amharic writing has several homophone families — different characters that represent the same spoken sound. The most common ones this package handles:

When you call transliterate(), all characters within a family produce the same Latin output, so a single transliteration covers all variant spellings.

Publishing config

php artisan vendor:publish --tag=amharic-transliteration-config

Publishing the data file (if you need custom mappings)

php artisan vendor:publish --tag=amharic-transliteration-data

License

MIT — see LICENSE.