strans
An input method daemon for CJK text entry on X11 and Wayland.
Inspired by 9front's ktrans. Threads communicate via CSP channels.
Dependencies
- plan9port
- Python 3 (for generated-map checks)
- dbus-1
- wayland-client, libxkbcommon (for Wayland support)
- gtk+-3.0 (optional, for GTK IM module)
Build
make
cd xim && make # XIM adapter
cd gtk && make docker && make install # GTK IM module
Unit tests use the sibling cutest Git repository as a submodule and do not
require the Wayland, D-Bus, GTK, or X11 development packages. Repository
mirrors must provide the same sibling; initialize it after cloning with
git submodule update --init:
make check # generated map + unit tests
make test TESTARGS=hangul # filtered unit tests only
make verify-map # generated-map check only
The suite covers the fixed-size UTF-8 string, hash table, trie fixtures, Japanese/Hangul/Telex state transitions, dictionary candidates, engine selection state, IPC request fields, and production map loading. Tests use explicit case tables, boundary values, and small regressions for repaired core contracts. Full IPC and GUI protocol stacks require separate integration checks.
Run
./strans map font &
For XIM apps:
./xim/strans-xim &
XMODIFIERS=@im=strans xterm
For GTK apps:
GTK_IM_MODULE=strans gedit
For IBus apps (kitty, foot, etc.):
GLFW_IM_MODULE=ibus kitty
For Wayland apps (text-input-v3 clients on wlroots compositors):
# nothing to set; the compositor relays text-input-v3 to strans
Strans itself is the IBus endpoint and the Wayland input-method-v2 client; no ibus-daemon or fcitx5 needed. Start strans after the compositor.
Usage
Switch input modes with Ctrl + key:
N Hiragana
K Katakana
S Hangul
T English
V Vietnamese (Telex)
P Toggle preedit echo
Type romanized input. Select candidates with 1-9 or arrow keys. Outside one-shot search, Tab or Enter commits.
Emoji and symbols
Ctrl+E starts a one-shot symbol search; it is not a mode. Any current preedit is committed, then the previous language is kept for the next input. Type an English alias or the phonetic keys of the current layout (Korean aliases work, for example). The candidate list is shown even when Ctrl+P has hidden normal preedit echo.
안녕 → Ctrl+E → smile → Enter → 😀
There is no auto-insert. Enter commits the first candidate (or the current
one); arrows and Tab move, and Esc cancels. Bare 1 through 9 select an existing
numbered row; a bare digit with no such row and 0 remain query text. Digit
aliases are kept in matching slots, so ^1, _2, and <3 produce ¹, ₂,
and ♥.
map/emoji.src is the source of truth: each UTF-8 TSV row is a result followed
by one or more tab-separated aliases. Aliases may be multilingual and ASCII
letters are case-insensitive. Results and aliases are limited to 64 Unicode
code points; results cannot contain whitespace. Run map/mkemoji > map/emoji.dict
after editing it; make verify-map checks the generated dictionary and the
Telex map.
😀 웃음 웃다 스마일 smile grin
Architecture
Threads communicate via CSP channels:
- imthread: keystroke processing, transliteration
- dictthread: dictionary lookup
- drawthread: preedit window rendering
- srvthread: IPC via unix socket
- ibusthread: IBus D-Bus endpoint for GLFW/kitty
- waylandthread: Wayland input-method-v2 + virtual-keyboard-v1
Adapters (strans-xim, im-strans.so) bridge X11/GTK events.
Files
strans.c input method engine
dict.c dictionary queries
win.c xcb window management
font.c truetype rendering (stb_truetype)
wayland.c wayland input-method-v2 adapter
map/ transliteration tables
font/ bundled CJK fonts
input-method-unstable-v2-*.{c,h} wayland-scanner output, vendored
virtual-keyboard-unstable-v1-*.{c,h}
The two Wayland protocols (input-method-v2, virtual-keyboard-v1) are wlroots-only and not in the upstream wayland-protocols package, so the generated client code is vendored. Regenerate with wayland-scanner if the XML upstream ever changes (it hasn't in years).