How to Configure and Test a Non-US Keymap on Haiku

A keymap answers “what character or role should this physical key produce?” Locale answers different questions about interface language and date, number, time, and currency formatting. Input methods handle more complex text entry such as Chinese, Japanese, or Korean. Configure and test each layer separately; changing the whole system to compensate for one application’s bug usually creates a second problem.

Record the physical keyboard and current behavior

Before editing, identify the keyboard’s printed standard and physical shape: ISO versus ANSI, language/country legends, extra key beside the left Shift, AltGr/Option labels, numeric keypad, and laptop-specific keys. A keymap with the right language but wrong physical layout can misplace the ISO key, backslash, or punctuation.

Open Preferences → Keymap. The on-screen keyboard darkens the key Haiku receives and places its assigned symbol in the sample field. Press every punctuation key without modifiers, then with Shift and Option. Test both left and right modifier keys. This separates a wrong mapping from a key the input driver never reports.

Write down the currently selected system keymap and shortcut-key mode. Do not start by modifying the supplied map; keep it as the known-good recovery path.

Select the closest supplied keymap

Choose the system map matching the printed keyboard and use the Layout menu to make the visualization match the physical geometry. These controls are independent: the selected map assigns characters, while the layout improves the panel’s physical representation.

Test this compact matrix in Keymap’s sample field:

Letters, number row, and every punctuation key.
Shifted symbols and Caps Lock behavior.
Option/AltGr combinations used by that language.
Dead-key sequences for accents such as acute, grave, diaeresis, tilde, or circumflex.
Return, Backspace, Tab, arrows, navigation keys, and keypad with Num Lock on/off.

Keymap marks dead keys in blue. Clicking one highlights in yellow the keys it can modify. A dead key intentionally waits for the next keystroke; it is not necessarily a stuck key. Test both a valid composition and the documented way to enter the accent itself.

Choose shortcut mode consciously

Keymap offers Switch shortcut key… between Haiku mode and Windows/Linux mode. In Haiku mode the Command role is normally on Alt; Windows/Linux mode moves common shortcut expectations toward Control. This is a system-wide behavioral choice, not a per-application remap.

After switching, verify copy, cut, paste, save, close, Find, Terminal control characters, workspace navigation, and app switching. Keep the distinction between keycap labels and Haiku roles: B_COMMAND_KEY, B_CONTROL_KEY, and B_OPTION_KEY are semantic modifiers, while the physical key assigned to each role can change.

Do not assign one physical key to several essential roles unless you understand the conflict. Use File → Set modifier keys… to inspect and change roles, and retain at least one functional Command and Control path.

Create a minimal custom map

If the closest supplied map has one or two errors, customize only those keys. In the Keymap panel, dragging one key onto another swaps them. You can also drag a character from CharacterMap or another application onto a key at the currently displayed modifier level.

Change one mapping, then repeat the relevant portion of the test matrix. Avoid a large set of edits followed by a single “looks right” check; that makes collisions and lost symbols difficult to locate.

Save through File → Save… under a new descriptive name in:

~/config/settings/Keymap/

Only maps stored there appear automatically in the user-defined list. Haiku stores the active selection separately in ~/config/settings/Key_map. Back up the custom map before experimentation, but do not overwrite package-supplied maps under /boot/system.

The Revert button restores the settings active when the preference panel opened. It is useful for the current editing session, not a substitute for knowing which supplied map can recover the machine later.

Use the command-line format only when necessary

The official Keymap guide documents a text representation for edits the graphical panel cannot express. Dump the active map without altering it:

keymap -d > MyKeymap

Make a second copy and edit that in a fixed-width text editor. The file contains physical key codes, modifier assignments, lock state, normal/Shift/Control/Option maps, and dead-key tables. A syntactically valid file can still make basic input unusable, so keep Terminal open and the original map accessible.

Temporarily load the text map with:

keymap -s < MyKeymap

Compile it to binary for import into the preference panel:

keymap -c < MyKeymap

The documented command produces keymap.out, which Keymap can open. A binary map can also be loaded using keymap -l < keymap.out. Do not invent older -o syntax from third-party tutorials; run keymap --help on the installed release if behavior differs.

Configure Locale and input methods separately

Open Preferences → Locale for preferred UI languages and fallbacks. Its Formatting tab independently selects date, time, number, and currency conventions. Changes apply immediately, although already running applications may need to restart.

Changing Locale does not relocate physical keys. Changing Keymap does not change UTF-8 encoding or translate applications. Haiku uses UTF-8 for keyboard characters; a correctly produced character rendered as a blank square usually points to font coverage, not key placement.

For Chinese, Japanese, or Korean composition, use an appropriate input method from HaikuDepot as the Keymap guide recommends. Complex input conversion is not equivalent to adding a few dead-key sequences.

Test across native and ported applications

After saving, test the sample field, StyledEdit or another native BTextView, Terminal, WebPositive, Tracker rename fields, and any important Qt or other ported application. Include shortcuts and composed non-ASCII text. Copy the result between applications and save/reopen it to verify UTF-8 survives.

If every native field is wrong in the same way, recheck the physical/keymap match. If one toolkit alone differs, capture application version, toolkit, selected map, shortcut mode, key pressed, expected character, actual character, and whether the Keymap sample field is correct. Report that path instead of globally remapping a good system key.

Finally reboot or log through the normal startup path and repeat punctuation, login-critical characters, and shortcuts. A usable non-US setup is one that remains recoverable, produces the expected Unicode text, and behaves consistently at each input layer—not merely one that types accented letters in a single panel.

Related:

Sources: