# 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 |
| `Ctrl+P` | Toggle popup preedit |

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.

## 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 and IBus frontend
xim/strans-xim      XIM frontend
gtk/im-strans.so    GTK 3 frontend
```

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 needs one to four font files. No fonts are bundled. Each file is
validated and registered with Pango as an application font. Pango shapes the
complete string and chooses glyph fallback from those fonts and the normal
system fonts; command-line file order is not an exact per-glyph fallback
contract.

`run.sh` uses installed Noto Color Emoji, DejaVu, Jigmo, or Noto CJK fonts when
available, or accepts explicit files. Supply a color emoji font such as Noto
Color Emoji to render emoji in color:

```sh
./run.sh
./run.sh /path/to/primary.ttf /path/to/fallback.ttc
```

The popup renderer requires Pango/PangoCairo 1.56 or newer and Cairo 1.18 or
newer.

The script starts the daemon and, when `DISPLAY` is set, the XIM frontend. It
restarts any existing `strans` processes 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 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

Data and third-party notices are in
[`docs/PROVENANCE.md`](docs/PROVENANCE.md) and
[`font/PROVENANCE`](font/PROVENANCE). The repository does not currently
declare a license for the strans source as a whole.