MAN.9FRONT.ORG RTFM


     KTRANS(1)                                               KTRANS(1)

     NAME
          ktrans - language transliterator

     SYNOPSIS
          ktrans [ -G ] [ -l lang ] [ kbdtap ]

     DESCRIPTION
          Ktrans transliterates a stream of keyboard events. Without
          any arguments, ktrans reads events from standard input and
          writes out converted events to stdout.  If a kbdtap file is
          given, it is used for both input and output instead.  Ktrans
          starts in a passthrough mode, echoing out the input with no
          conversions. Control characters are used to give instruc-
          tions, the following control sequences are used to switch
          between languages:

          ctl-t
               English (Passthrough).

          ctl-n
               Japanese Hiragana.

          ctl-k
               Japanese Katakana.

          ctl-c
               Chinese.

          ctl-s
               Korean.

          ctl-v
               Vietnamese.

     CONVERSION
          Conversion is done in two layers, an implicit layer for
          unambiguous mappings, and an explicit layer for selecting
          one match out of a list of ambiguous matches. The following
          control characters are used for conversion instructions.

          ctl-\
               Explicitly match the current input, consecutive inputs
               of ctl-\ will cycle through all the possible options.

          ctl-l
               Reset the current input buffer.

          The implicit layer happens automatically as characters are
          input, transforming a consecutive set of key strokes in to
          their rune counterpart. A series of runes may then be

     KTRANS(1)                                               KTRANS(1)

          explicitly matched by cycling through a list of options.
          Ktrans automatically maintains a buffer of the current
          series of key strokes being considered for an explicit
          match, and resets that buffer on logical "word" breaks
          depending on the language.  However in some cases the auto-
          matic hinting will be insufficient.

          Input is always passed along, when a match is found Ktrans
          will emit backspaces to clear the input sequence and replace
          it with the matched sequence.

     DISPLAY
          Ktrans will provide a graphical display of current explicit
          conversion candidates as implicit conversion is done. Candi-
          dates are highlighted as a user cycles through them. At the
          bottom of the list is an exit button for quitting the pro-
          gram. Keyboard input typed in to the window is transliter-
          ated but discarded, providing a scratch input space. The -G
          option disables this display.

     KEY MAPPING
          For convenience, the control characters used by ktrans can
          be mapped directly to physical keys through modifications of
          the kbmap (see kbdfs(8)). The /sys/lib/kbmap/jp mapping will
          turn language input keys present on Japanese A01/106/109(A)
          in to control sequences matching their label:

          Henkan
               Convert to Kanji (ctl-\)

          Muhenkan
               Clear Kanji buffer (ctl-l)

          Hiragana / Katakana
               Switch to Hiragana (ctl-n)

          Shift + Hiragana / Katakana
               Switch to Katakana (ctl-k)

          Hankaku / Zenkaku
               Switch to Hiragana (ctl-n)

          Shift + Hankaku / Zenkaku
               Switch to passthrough (ctl-t)

          Shift + Space
               Convert to Kanji (ctl-\).  This is a fallback for key-
               boards without a physical Henkan key.

     DICTIONARIES
          All implicit and explicit matching dictionaries are provided
          as plain text files within /lib/ktrans.  The formats of

     KTRANS(1)                                               KTRANS(1)

          which are specified within ktrans(6). Users may create and
          or modify existing dictionaries by binding over the system
          defaults.

          For backwards compatibility the jisho and zidian environment
          variables may also be set to pick explicit lookup dictionar-
          ies for Japanese and Chinese respectfully.

     LANGUAGES
        JAPANESE
          The Hiragana and Katakana modes implicitly turn Hepburn rep-
          resentations in to their Kana counterparts. Explicit conver-
          sions combine sequences of Hiragana in to Kanji.

          Capital Latin input is used for hinting. For adjectives and
          verbs, a single capital is used as an Okurigana hint. For
          example, 動かす is typed as 'ugoKasu[^\]'. The hint serves two
          purposes, it is provided as part of the explicit sequence
          for Kanji lookup and denotes that the following runes are
          Okurigana.

          For particles, the entire Kana may be input in upper case.
          This similarly denotes the end of the Kanji portion of the
          sequence, but is not used as part of the lookup sequence
          itself. So to write 私の猫 the user types
          "watashiNO[^\]neko[^\]". Note that in both cases we have
          successfully communicated to ktrans when to reset the
          explicit match buffer without needing to explicitly give a
          ctl-l character.

        CHINESE
          Implicit conversion converts punctuation. Explicit matches
          use a dictionary to convert a series of Latin characters
          into Hanzi. By default a Wubizixing input dictionary is
          used. Additionally a Pinyin input dictionary is provided.

        VIETNAMESE
          Implicit conversion is modeled after Telex, supporting stan-
          dard diacritic suffixes.

        KOREAN
          Mapping is done by emulating a Dubeolsik layout, with each
          Latin character mapping to a single Jamo. Sequences of up to
          three Jamo are automatically converted to Hangul syllables.

     EXAMPLES
          To type the following Japanese text:

          私は毎日35以歩いて 更に10電車に乗って学校にいます
           健康の維にも役だっていますが なかなかたのしいものです

          your keyboard typing stream should be:

     KTRANS(1)                                               KTRANS(1)

          watashiHA[^\]mainichi[^\]35[^l]fun[^\]ijou[^\]aruIte,[^\]
          saraNI[^\]10[^l]fun[^\]denshaNI[^\]noTte[^\]gakkouNI[^\]
          kayoImasu.[\n]kenkouNO[^\]ijiNImo[^\]yakuDAtteimasuga,[^\]
          nakanakatanoshiImonodesu.[\n]

          where [^\] and [^l] indicate 'ctl-\' and 'ctl-l', respec-
          tively.

     SOURCE
          /sys/src/cmd/ktrans

     SEE ALSO
          ktrans(6), rio(4), kbdfs(8)

     BUGS
          There is no hint from rio when the user moves the cursor, as
          such moving it is unlikely to result in what the user
          expects.

          Plan 9 lacks support for rendering combinational Unicode
          sequences, limiting the use of some code ranges.

     HISTORY
          Ktrans was originally written by Kenji Okamoto in August of
          2000 for the 2nd edition of Plan 9.  It was imported in to
          9front in July of 2022, with patches by several contribu-
          tors. It was towed inside the environment during the 2022
          9front hackathon.