strans

strans is a small, single-user input method for Korean, Japanese, English, emoji, and symbols. It provides one engine for IBus, XIM, and GTK 3. Vietnamese Telex is also available as a compatibility mode.

Input modes

Key	Mode
`Ctrl+N`	Japanese Hiragana and Kanji conversion
`Ctrl+K`	Japanese Katakana
`Ctrl+S`	Korean Hangul (2-beolsik)
`Ctrl+T`	English
`Ctrl+V`	Vietnamese Telex
`Ctrl+E`	Emoji and symbol search
`Ctrl+H`	One-shot Hanja search

Use Up/Down to move through candidates and PageUp/PageDown to move by nine without wrapping. An unmodified 1-9 selects that row on the current page. Enter confirms the selection, and 0 commits the current reading without conversion. Tab confirms an ordinary candidate; in a temporary Emoji or Hanja search, Tab and Shift-Tab wrap through the results. Esc cancels composition.

Hiragana mode composes a complete reading before offering Kanji candidates. Katakana mode does not perform Kanji conversion. Emoji and Hanja searches return to the previous mode after use. Hanja lookup currently supports one modern Hangul syllable at a time.

Preedit and candidates

Frontend	Preedit	Candidates
GTK 3 and IBus	inline in the client	strans popup
XIM PreeditCallbacks	inline through XIM callbacks	strans popup
XIM PreeditPosition	strans popup	strans popup
XIM PreeditNothing	strans popup	strans popup

XIM supports UTF8_STRING and COMPOUND_TEXT. Position clients place the popup from XNSpotLocation; otherwise XIM placement falls back to the bottom of the focus or client window.

The popup is an X11 window, XIM is X11-only, and GTK popup placement converts the GTK caret to X11 root coordinates. There is no native Wayland popup surface or Wayland caret positioning. GTK and IBus clients can still use inline preedit where their display environment supports it.

Build and test

Initialize the bundled test library, then use the pinned Docker environment for a reproducible build:

git submodule update --init
make docker-image
make docker-build

Build output:

strans              daemon with IBus and XIM frontends
gtk/im-strans.so    GTK 3 frontend module

Tests have three tiers:

make check          # generated-map validation and focused unit tests
make check-live     # one IBus, GTK, XIM, and IPC daemon smoke
make check-stress   # randomized, capacity, collision, failure, and restart tests

UNITARGS filters only the focused C unit suite, for example make check UNITARGS=hangul. It does not select or skip live and stress tests. make docker-check force-rebuilds and runs all three tiers in the container; run make docker-image first after changing Dockerfile.

Native Linux builds require a C toolchain, Make, pkg-config, Python 3, and cmp/diff, plus:

Plan 9 port (9c, 9l, libthread, and libbio);
D-Bus development files;
XCB, XCB RandR, xcb-imdkit, xkbcommon, and xkbcommon-x11;
Pango, PangoCairo, Cairo, and Fontconfig;
GTK 3, plus libibus and Xlib for the live clients;
Xvfb for the X11 live tests;
a working C.UTF-8 locale and fonts covering Latin, CJK, and emoji.

The package names used by the canonical Arch Linux image are listed in Dockerfile.

Run

The popup uses the normal system fonts found by Pango and Fontconfig; no font file argument or system-wide strans installation is required. Run it directly from the build tree:

./run.sh
# equivalently
./strans map

run.sh stays in the foreground and replaces itself with the daemon. Stop it with Ctrl-C or let a service supervisor own it. It neither finds nor kills other strans processes. Endpoint collisions and requested frontend startup failures make the process exit non-zero.

The build does not copy or install the daemon or its data. ./strans DIR opens hira.map, kata.map, telex.map, kanji.dict, emoji.dict, and hanja.dict from DIR at runtime; run.sh passes the tracked map/ directory. Only the GTK subdirectory has install and uninstall targets.

Pango shapes the complete string and selects glyph fallback from the system font set.

The popup renderer uses Pango/PangoCairo and Cairo. When DISPLAY is set, strans starts its XIM worker in the same process.

Configure clients as needed:

# XIM
export XMODIFIERS=@im=strans

# GTK 3 module
doas make -C gtk install
export GTK_IM_MODULE=strans

# IBus client example
GLFW_IM_MODULE=ibus kitty

The GTK module directory is derived from GTK's pkg-config libdir and binary version. It can be overridden with GTK_MODULE_DIR; DESTDIR staging is supported and deliberately skips the host module-cache update. Remove a native installation with:

doas make -C gtk uninstall

strans provides its own IBus endpoint; ibus-daemon and fcitx are not required. Without DISPLAY, the daemon and IBus frontend still work, but XIM is not started and the popup is disabled.

Dictionary data

After changing an input source, regenerate and verify the dictionaries:

map/mkemoji >map/emoji.dict
map/mkhanja >map/hanja.dict
make verify-map

See map/README for Hanja import and Japanese dictionary generation.

Benchmark

make bench builds bench/bench. With the daemon stopped, ./bench.sh starts one build-tree instance, warms it up, and records the workload with Linux perf. It requires perf and permission to profile the daemon, and writes bench/perf.data.

Licensing

Third-party license notices are in LICENSES. The repository does not currently declare a license for the strans source as a whole.

5.6 KiB Raw Blame History