Tâi-gí Telex

Tâi-gí Telex is a Taiwanese input method with Telex-style tone keys for macOS. It supports both Tâi-lô (TL) and Pe̍h-ōe-jī (POJ) romanization systems.

Live Demo: https://telex.kahiok.com

User Guide

Download & Install

Install with Homebrew:

brew install --cask madmaxieee/tap/taigi-telex

Alternative: install the package manually

Download Latest Release — Recommended for most users.

Nightly builds are pre-release versions with the latest changes. They may be less stable. Download here if you want to test new features.

Install the Package

1. Download the TaigiTelex-x.x.x.pkg file from the link above
2. Double-click the downloaded .pkg file to start the installer
3. Follow the prompts to complete installation

If you see "cannot be opened" or "unidentified developer":

This package isn't signed with an Apple Developer certificate, which is normal for open-source projects. To allow it:

1. Open System Settings → Privacy & Security
2. Scroll to the Security section
3. Click Open Anyway next to the message about TaigiTelex
4. Enter your password if prompted, then confirm

Add the Input Method

1. Go to System Settings → Keyboard → Input Sources
2. Click the Edit… button (or + on older macOS versions)
3. Search for Tâi-gí Telex under Chinese, Traditional and add it
4. Select it from the input menu in your menu bar to start typing

Tip: If Tâi-gí Telex doesn't appear in the list, log out of your Mac and log back in, then try again.

Basic Rules

Type letters normally. Special keys modify the output:

Consonant Mappings

Key	TL Output	POJ Output	Usage
c	tsh	chh	TL: ts / POJ: chh aspirated affricate
C	Tsh	Chh	Capital form
z	ts	ch	TL: tsh / POJ: ch unaspirated affricate
Z	Ts	Ch	Capital form
f	-	-	Hyphen shorthand (both modes)

POJ-Specific Features

When using POJ mode, you can type:

Input	Output	Description
nn	ⁿ	Nasalization (superscript n)
NN	ⁿ	Capital input also works
oo	o͘	POJ-specific vowel (o with dot)
OO	O͘	Capital form

To type literal nn or oo, press the key three times (e.g., nnn → nn, ooo → oo).

Tone Marks

Add tone marks by typing the corresponding key at the end of a syllable (same in both modes, except 9th tone):

Key	Tone	Example (TL)	Example (POJ)
v	2nd	av → á	av → á
y	3rd	ay → à	ay → à
d	5th	ad → â	ad → â
w	7th	aw → ā	aw → ā
x	8th	ax → a̍	ax → a̍
q	9th	aq → a̋	aq → ă

Examples

Tâi-lô (TL) Mode

Input	Output	Notes
te + v	té	Second tone
khoo + y	khòo	Third tone
lang + d	lâng	Fifth tone
kang + w	kāng	Seventh tone
tit + x	ti̍t	Eighth tone
zang + q	tsáng	Ninth tone (consonant: ts)
z	ts	Consonant replacement
c	tsh	Consonant replacement
taid + f + giv	tâi-gí	Hyphen shorthand (f)

POJ Mode

Input	Output	Notes
hoo + v	hó͘	Second tone (with long o vowel)
pa + y	pà	Third tone
kau + d	kâu	Fifth tone
ciunn + w	chhiūⁿ	Seventh tone (with consonant replacement)
lok + x	lo̍k	Eighth tone
sann	saⁿ	Nasalization (nn → ⁿ)
z	ch	Consonant replacement
c	chh	Consonant replacement
taid + f + giv	tâi-gí	Hyphen shorthand (f)

Tone Mark Placement

Tone marks are automatically placed on the correct vowel:

Tâi-lô (TL) priority order: a > e > o > u > i

• Exceptions:
  • iu → mark on u (e.g., liuv → liú)
  • ui → mark on i (e.g., huiy → hùi)

POJ priority order: o͘ > a > e > o > u > i

• Exceptions:
  • eo → mark on e (e.g., heov → hé + o)
  • oe → mark on o (e.g., hoey → hòe)

Both modes support ng and m as vowels when no other vowels are present.

Tips

• Press the same tone key twice to type the letter itself (e.g., avv → av)
• Press the same consonant key twice to type it literally (e.g., zz → z, cc → c)
• In POJ mode, press a double vowel key three times to escape (e.g., nnn → nn, ooo → oo)
• Non-letter characters (space, comma, period, numbers) automatically commit the current composition
• Press return key to commit current buffer
• Use Caps Lock to switch between Tâi-gí Telex modes and English, like any Chinese input method

Contribution Guide

Install dependencies

Contributing requires macOS, a Swift toolchain, CMake, and Ninja. mise can install CMake and Ninja, but Swift is provided by Xcode or the Xcode Command Line Tools.

brew install cmake ninja
# or if you use mise
mise i

Build

Per ADR 0001, CMake is the authoritative build system for the input method. Swift Package Manager supports tests, fuzzing, and source tooling; it does not replace the CMake build.

cmake -B build -G Ninja \
  -DARCH=arm64 \
  -DCMAKE_BUILD_TYPE=Release
cmake --build build
# or if you use mise
mise run build

Verify and test

Run the complete pre-package verification gate, which runs unit tests, deterministic bounded fuzzing, and the authoritative CMake build:

mise run verify

Individual development commands are also available:

mise run test    # Swift unit tests
mise run fuzz    # Fuzz harness
mise run format  # Format Swift source files

Install

cmake --install build
# or if you use mise
mise run install

• On first time installation, log out and log back in, then in System Settings -> Keyboard -> Input Sources (Edit), Tâi-gí Telex from Chinese, Traditional.
• On further installations, switch to another input method, pkill TaigiTelex, then switch back.

Package

To build a distributable PKG installer:

mise run package

The PKG will be created at build/TaigiTelex-x.x.x.pkg.

Acknowledgement

• toyimk Thanks toyimk for the build system setup
• macSKK Thanks macSKK for architecture reference