![[me]](logo/logo.png){kind=logo}
translate-key(2)
translate-key(2)translate-key - Translate key
n translate-key [ "from" ["to"] ]
translate-key may be used to convert any given input key sequence to another single key. translate-key operates at a very low level, before MicroEmacs attempts to evaluate keyboard bindings, so it may be used to solve a variety of keyboard problems such as special language characters and UNIX termcap key sequence bindings (see below).
If a positive numeric argument n is given it is used to set the time in milliseconds MicroEmacs waits for another key to be pressed before continuing, the default time use when no argument is supplied is 250ms.
If a numeric argument n of -1 is specified then the "to" argument is not required and the "from" character sequence is removed from the translate key table.
If a numeric argument n of -2 is specified then the "to" argument is not required; the command returns the key sequence "from" is currently mapped to in variable $result(5) or returns an error if it is not currently mapped. Note that if the given character sequence is only part of a mapping and is not directly mapped itself (for example, "C-[ [" in the listing below) the mapping string returned is an encoded null character ("\x00").
If a numeric argument n of 0 is specified then no arguments are required; the current translation table is dumped to buffer "*translate-key*". Following is a sample output:
"C-h" ......................... "backspace" "C-[" ......................... "esc" "C-[ [ 1 ~" ................... "delete" "C-[ [ 1 1 ~" ................. "f1" "C-[ [ 1 2 ~" ................. "f2" "C-[ [ 1 3 ~" ................. "f3" "C-[ [ 1 4 ~" ................. "f4" "C-[ [ B" ..................... "down" "C-[ [ 4 ~" ................... "end" "C-[ [ 2 ~" ................... "insert" "C-[ [ 3 ~" ................... "home" "C-[ [ D" ..................... "left" "C-[ [ 6 ~" ................... "page-down" "C-[ [ 5 ~" ................... "page-up" "C-[ [ C" ..................... "right" "C-[ [ A" ..................... "up" "C-[ [ V" ..................... "page-up" "C-[ [ U" ..................... "page-down" "C-m" ......................... "return" "C-i" ......................... "tab" "\x7F" ........................ "backspace"
Foreign keyboards (non-US/UK) use a variety of key sequences, not recognized by MicroEmacs, to expand the keyboard character range to cope with accented characters. For example, on a German keyboard 'AltGr-m' (recognized as 'A-C-m') is used to insert a Greek mu (or micro sign). On a Belgian keyboard 'AltGr-9' inserts a '{' character.
Many foreign keyboards are already directly supported by MicroEmacs and the keyboard specifics of a country have been understood and resolved. In these cases the Keyboard configuration in user-setup(3) may be used for the country location.
If MicroEmacs does not support your keyboard, translate-key may be used to fix any key input problems. For the aforementioned examples the following translate-key commands would be required:
; translate AltGr-m to a Greek mu (char 0xb5)
translate-key "A-C-m" "\xB5"
; translate AltGr-9 to a '{'
translate-key "A-C-9" "{"
The problem is complicated further on Microsoft Window's platforms by the simultaneous generation of 2 keys for some Alt-Gr key combinations (this is a side effect of endeavoring to capture all key combinations in this environment). For the Belgian keyboard example, on Win32 platforms an 'AltGr-9' generates an 'A-C-9' key first followed immediately by an 'A-C-{'. As both keys are generated in quick succession this is unexpected and confusing.
When the key is first pressed on a poorly configured system the error "[Key not bound "A-C-{"]" is given even when using the command describe-key(2) as the key described will be 'A-C-9' and then the 'A-C-{' key is generated and interpreted creating the error message.
The variable $recent-keys(5) can be used to diagnose this problem and to obtain the 2 keys generated; alternatively use the macro below:
define-macro report-2-keys ml-write "Press key 1" set-variable #l0 @cgk ml-write "Press key 2" set-variable #l1 @cgk ml-write &spr "[The following keys where pressed: \"%s\" \"%s\"]" #l0 #l1 !emacro
When executed the user is prompted for the first key; press the required key sequence (in this case 'AltGr-9'), if you are not prompted for the second key and the result is immediately returned then the key you pressed has generated 2 keys, both of which will be given in the print out, i.e.:
"[The following keys where pressed: "A-C-9" "A-C-{"]"
The translate-key required to fix this type of problem would be:
translate-key "A-C-9 A-C-{" "{"
If your keyboard is not directly supported by MicroEmacs, please submit the keyboard name and platform with a working translate-key configuration to JASSPA as a BUG.
translate-key may also be used to interpret non-standard key sequences for UNIX termcap platforms to standard MicroEmacs keys. Non-standard keys, such as the cursor keys, have system dependent key sequences. The output from these keys usually take the form:
^[[X or ^[[DX or ^[[DDX or ^[[DDD
where ^[ is the escape key (27), D is a digit and X is any character. These keys may be bound to the standard keys, for example the typical output of the cursor keys may be translated as follows:
^[[A = up, ^[[B = down, ^[[C = right and ^[[D = left
The "from" string is specified as this key sequence and the "to" string is simply the key it is to be bound to, see global-bind-key(2) for a guide to the string format. For the above example the following set of translations are required:
translate-key "esc [ A" "up" translate-key "esc [ B" "down" translate-key "esc [ C" "right" translate-key "esc [ D" "left"
Note that MicroEmacs interprets \e as an escape key. More obscure keys tend to be very platform specific, following are some examples:
translate-key "esc [ 2 ~" "insert" translate-key "esc [ 5 ~" "page-up" translate-key "esc [ 5 ^" "C-page-up"
Using the positive numeric argument it is possible to reduce the delay and there by increase usability is some features. For instance, in the Mouse configuration of user-setup there is an option to 'Simulate 3 Buttons' which translates a rapid left and right button press into a middle button press. This is implemented using translate-key as follows:
10 translate-key "mouse-pick-1 mouse-pick-3" "mouse-pick-2" 10 translate-key "mouse-pick-3 mouse-pick-1" "mouse-pick-2" 10 translate-key "mouse-drop-1 mouse-drop-3" "mouse-drop-2" 10 translate-key "mouse-drop-3 mouse-drop-1" "mouse-drop-2"
When a mouse-pick-1 key is generated MicroEmacs must wait to see if a mouse-pick-3 key is next and therefore translate both to a single mouse-pick-2 key. This wait time is usually a quarter of a second but this makes the left button unusable for dragging regions etc as the delay is too long. By giving a argument of 10ms the delay is long enough for a simultaneous left and right button press but short enough for the left button to still be usable on its own.
The positive numeric argument can be very useful for delaying MicroEmacs as well, for example, the character string "'e" can be converted to e-accute using expand-iso-accents(3). This could be performed automatically using translate-key as follows:
1000 translate-key "' e" "\xE9"
The larger 1 second delay give the user enough time to type the 'e' after the ''' character.
The following are a set of known translations courtesy of -Th.
; fix Backspace using Putty
-1 translate-key "C-h" ; remove translation to "backspace"
translate-key "\x7F" "backspace" ; Backspace key
; fix del, home keys termcap/Putty/Solaris ME20040403
translate-key "C-[ [ 3 ~" "delete" ; ^[[3~ ('cat' output)
translate-key "C-[ [ 1 ~" "home" ; ^[[1~
; add support for termcap/Putty/Solaris
translate-key "C-[ O A" "C-up" ; ctrl up ^[OA
translate-key "C-[ O B" "C-down" ; ctrl down ^[OB
translate-key "C-[ O D" "C-left" ; ctrl left ^[OD
translate-key "C-[ O C" "C-right" ; ctrl right ^[OC
;-----
; SuSE xterm console mode ('me -n')
; 12-Jan-06 SuSE10/kde/gnome
;-----
translate-key "C-[ [ 1 ; 5 A" "C-up"
translate-key "C-[ [ 1 ; 5 B" "C-down"
translate-key "C-[ [ 1 ; 5 C" "C-right"
translate-key "C-[ [ 1 ; 5 D" "C-left"
translate-key "C-[ [ 1 ; 2 A" "S-up"
translate-key "C-[ [ 1 ; 2 B" "S-down"
translate-key "C-[ [ 1 ; 2 C" "S-right"
translate-key "C-[ [ 1 ; 2 D" "S-left"
translate-key "C-[ [ H" "home"
translate-key "C-[ [ F" "end"
translate-key "C-[ [ 1 ; 5 H" "c-home"
translate-key "C-[ [ 1 ; 5 F" "c-end"
translate-key "C-[ [ 5 ; 5 ~" "C-page-up"
translate-key "C-[ [ 6 ; 5 ~" "C-page-down"
translate-key "C-[ [ 2 9 ~" "menu" ; context menu key
The concept of standardized key-bindings is very important for cross platform use and maintenance.
Refer to global-bind-key(2) for a list of standard bindings.
One of the easiest ways of obtaining a key sequence is to run sh(1) which does not attempt to interpret these keys so when a key is pressed (followed by <RETURN>) the following type of error message is usually generated:
sh: ^[[2~: not found.
where ^[[2~ is the required key sequence. Another method of obtaining these key sequences is to start MicroEmacs, use start-kbd-macro(2) to start a macro definition, press the required keys and then use end-kbd-macro(2) followed by name-kbd-macro(2) and insert-macro(2) to display the keys pressed.
The key sequences generated for these keys are dependent on the machine displaying MicroEmacs as opposed to the machine running it. Often they are the same machine, but when they are not there is no easy method of determining the displaying machine and therefore correctly configuring MicroEmacs.
A better way of obtaining this cross platform consistency is to create an XTerm app-defaults setup file with the correct VT100 key translations, e.g. the setup file could contain the following
*vt100.translations: #override \
Shift<Key>Tab: string("\033[Z") \n\
<Key>BackSpace: string("\177") \n\
<Key>Delete: string("\033[1~") \n\
<Key>Insert: string("\033[2~") \n\
<Key>Home: string("\033[3~") \n\
<Key>End: string("\033[4~") \n\
<Key>Prior: string("\033[5~") \n\
<Key>Next: string("\033[6~") \n\
Ctrl<Key>Up: string("\033Oa") \n\
Ctrl<Key>Down: string("\033Ob") \n\
Ctrl<Key>Right: string("\033Oc") \n\
Ctrl<Key>Left: string("\033Od") \n\
Shift<Key>Up: string("\033[a") \n\
Shift<Key>Down: string("\033[b") \n\
Shift<Key>Right: string("\033[c") \n\
Shift<Key>Left: string("\033[d") \n
By using the environment variable XUSERFILESEARCHPATH to ensure that this configuration file is found instead of the system one (found in /usr/lib/X11/app-defaults), the key sequences will then be the same across all platforms. See manual page on xterm(1) for more information.
expand-iso-accents(3), user-setup(3), describe-key(2), global-bind-key(2), start-kbd-macro(2), $result(5), xterm(1), sh(1).
Ref: translate-key(2) File: m2cmd133.2 Date: 2026/02/17
(c) Copyright JASSPA 2026