# 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, `Enter` or `1`-`9` to select,
`Tab` to cycle temporary search results, and `Esc` to cancel. `0` commits the
current reading without conversion.

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.

## Build and test

Docker is the supported build environment:

```sh
git submodule update --init
make docker-image
make docker-build
make docker-check
```

Build output:

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

Use `make docker-check TESTARGS=hangul` to run selected C tests. Native
`make all`, `make check`, and `make bench` are also available when the
dependencies listed in [`Dockerfile`](Dockerfile) are installed.

## 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:

```sh
./run.sh
# equivalently
./strans map
```

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. `run.sh` restarts the
existing `strans` process owned by the current user.

Configure clients as needed:

```sh
# XIM
export XMODIFIERS=@im=strans

# GTK 3 module
doas make -C gtk install

# IBus client example
GLFW_IM_MODULE=ibus kitty
```

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:

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

See [`map/README`](map/README) for Hanja import and Japanese dictionary
generation.

## Licensing

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