tifinagh-convert

Why

Amazigh (Tamazight) remains one of the most under-resourced languages in NLP and software. Developers building Tifinagh-aware tools — OCR pipelines, keyboards, dictionaries — have had to re-implement the same script conversion logic from scratch. This package is the shared infrastructure that should have existed.

Tifinagh ↔ Latin script converter for the Amazigh (Tamazight) language.

Zero dependencies. TypeScript-first. Based on the official IRCAM Neo-Tifinagh standard and the ALA-LC / BGN-PCGN romanization tables.

npm install tifinagh-convert

Quick start

import { convert, detect, alphabet } from 'tifinagh-convert'

// Tifinagh → Latin
const r1 = convert('ⵜⴰⵎⵓⵔⵜ', { to: 'latin' })
console.log(r1.output)   // 'tamurt'

// Latin → Tifinagh
const r2 = convert('tamurt', { from: 'latin', to: 'tifinagh' })
console.log(r2.output)   // 'ⵜⴰⵎⵓⵔⵜ'

// Auto-detect source script
const r3 = convert('ⵎⵓⵔ', { to: 'latin' })
console.log(r3.output)   // 'mur'

API

convert(text, options)

| Option | Type | Default | Description | |----------|--------------------------|--------------|------------------------------------| | to | 'tifinagh' \| 'latin' | required | Target script | | from | 'tifinagh' \| 'latin' | auto-detect | Source script (optional) | | region | 'morocco' \| 'algeria' | 'morocco' | Affects letter inventory |

Returns ConvertResult:

{
  output:   string              // converted text
  from:     Script
  to:       Script
  region:   Region
  detected: boolean             // true if script was auto-detected
  warnings: ConversionWarning[] // ambiguous or unknown characters
}

Each warning:

{
  code:     'AMBIGUOUS_DIGRAPH' | 'UNKNOWN_CHAR' | 'APPROXIMATED_CHAR'
  message:  string
  position: number  // zero-based index in the input string
}

detect(text)

Auto-detects which script a string is written in.

detect('ⵜⴰⵎⵓⵔⵜ') // { script: 'tifinagh', confidence: 1 }
detect('tamurt')   // { script: 'latin',    confidence: 1 }
detect('مراكش')    // { script: 'arabic',   confidence: 1 }

alphabet(options?)

Returns the Amazigh alphabet as a structured list.

alphabet()                      // all letters (Morocco standard)
alphabet({ type: 'vowel' })     // only the 4 vowels: ⴰ ⴻ ⵉ ⵓ
alphabet({ region: 'algeria' }) // includes Algeria-only letters

Each entry:

{
  tifinagh: string
  unicode:  string
  latin:    string
  type:     'vowel' | 'consonant' | 'modifier'
  region?:  'algeria'
  note?:    string
}

Input aliases (Latin → Tifinagh)

When typing Amazigh in Latin without special characters, people use informal conventions online. This package accepts all of them:

| You type | You get | Note | |----------|---------|------| | gh or v or ɣ | ⵖ | voiced velar fricative | | kh or x | ⵅ | voiceless velar fricative | | sh or ch or c | ⵛ | | | o | ⵓ | same sound as u in Amazigh | | 3 or ɛ | ⵄ | ayin | | T or ṭ | ⵟ | emphatic t | | H or ḥ | ⵃ | emphatic h | | R or ṛ or Ṛ | ⵕ | emphatic r | | S or ṣ or Ṣ | ⵚ | emphatic s |

convert('3icha',  { from: 'latin', to: 'tifinagh' }).output  // ⵄⵉⵛⴰ
convert('lakhSas', { from: 'latin', to: 'tifinagh' }).output // ⵍⴰⵅⵚⴰⵙ
convert('tachelHit', { from: 'latin', to: 'tifinagh' }).output // ⵜⴰⵛⴻⵍⵃⵉⵜ

The output direction (Tifinagh → Latin) always uses the standard romanization — ɣ for ⵖ, not gh or v.

Digraph disambiguation (Latin → Tifinagh)

gh is an alias for ⵖ. If you ever need to write a literal g followed by h as two separate letters, use a middle dot (U+00B7):

convert('agham',  { from: 'latin', to: 'tifinagh' }) // ⴰⵖⴰⵎ
convert('ag·ham', { from: 'latin', to: 'tifinagh' }) // ⴰⴳⵀⴰⵎ  (g then h)

Labialized consonants

Some Tifinagh consonants are written as two Unicode codepoints (base letter + tamatart U+2D6F) but represent one sound. The converter handles them automatically:

convert('\u2D3D\u2D6F', { from: 'tifinagh', to: 'latin' }) // 'kʷ'

Regional variants

Algeria uses one letter not in the Moroccan IRCAM standard (U+2D35 / ǧ). Pass region: 'algeria' to enable it:

convert('\u2D35am', { from: 'tifinagh', to: 'latin', region: 'algeria' }) // 'ǧam'

Data sources

• ALA-LC Tamazight Romanization — Library of Congress
• BGN/PCGN Romanization of Neo-Tifinagh — UK Government (2022)
• Unicode Tifinagh block U+2D30–U+2D7F
• IRCAM — Royal Institute of Amazigh Culture

Roadmap

• [x] Tifinagh → Latin
• [x] Latin → Tifinagh
• [x] Auto-detect script
• [x] Morocco / Algeria regional variants
• [x] Informal input aliases (gh, kh, sh, 3, v, c…)
• [ ] Arabic script support (v0.2)
• [ ] Gemination rules
• [ ] Tuareg / historical Tifinagh variants

Contributing

Corrections to the mapping table, dialect coverage, or documentation are welcome. Open an issue or pull request at: https://github.com/hamza-bouqssim/tifinagh-convert

License

MIT © Hamza BOUQSSIM