Function: key-translate

key-translate is an interactive and byte-compiled function defined in keymap.el.gz.

Signature

(key-translate FROM TO)

Documentation

Translate character FROM to TO on the current terminal.

This function creates a keyboard-translate-table if necessary and then modifies one entry in it.

Both FROM and TO should be specified by strings that satisfy key-valid-p. If TO is nil, remove any existing translation for FROM.

Interactively, prompt for FROM and TO with read-char.

View in manual

Probably introduced at or before Emacs version 30.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/keymap.el.gz
(defun key-translate (from to)
  "Translate character FROM to TO on the current terminal.

This function creates a `keyboard-translate-table' if necessary
and then modifies one entry in it.

Both FROM and TO should be specified by strings that satisfy `key-valid-p'.
If TO is nil, remove any existing translation for FROM.

Interactively, prompt for FROM and TO with `read-char'."
  (declare (compiler-macro
            (lambda (form) (keymap--compile-check from to) form)))
  ;; Using `key-description' is a necessary evil here, so that the
  ;; values can be passed to keymap-* functions, even though those
  ;; functions immediately undo it with `key-parse'.
  (interactive `(,(key-description `[,(read-char "From: ")])
                 ,(key-description `[,(read-char "To: ")])))
  (keymap--check from)
  (when to
    (keymap--check to))
  (let ((from-key (key-parse from))
        (to-key (and to (key-parse to))))
    (cond
     ((= (length from-key) 0)
      (error "FROM key is empty"))
     ((> (length from-key) 1)
      (error "FROM key %s is not a single key" from)))
    (cond
     ((and to (= (length to-key) 0))
      (error "TO key is empty"))
     ((and to (> (length to-key) 1))
      (error "TO key %s is not a single key" to)))
    (or (char-table-p keyboard-translate-table)
        (setq keyboard-translate-table
              (make-char-table 'keyboard-translate-table nil)))
    (aset keyboard-translate-table
          (aref from-key 0)
          (and to (aref to-key 0)))))