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:

Family	Characters	Sound
አ / ዐ	`አ` `ኣ` `ዐ` `ዓ`	a
ሀ / ሐ / ኀ	`ሀ` `ሐ` `ኀ` (and their vowel forms)	h
ሰ / ሠ	`ሰ` `ሠ` (and their vowel forms)	s
ጸ / ፀ	`ጸ` `ፀ` (and their vowel forms)	ts
ጰ / ፐ	`ጰ` `ፐ` (and their vowel forms)	p

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.

wossnap / amharic-transliteration

Maintainers

Package info

Statistics

Security