diff --git a/README.md b/README.md index 178c0ae..fe62f4e 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,87 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/rvaiya/keyd) · [上游 README](https://github.com/rvaiya/keyd/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 + [![Kofi](https://badgen.net/badge/icon/kofi?icon=kofi&label)](https://ko-fi.com/rvaiya) # Impetus [![Packaging status](https://repology.org/badge/tiny-repos/keyd.svg)](https://repology.org/project/keyd/versions) -Linux lacks a good key remapping solution. In order to achieve satisfactory -results a medley of tools need to be employed (e.g xcape, xmodmap) with the end -result often being tethered to a specified environment (X11). keyd attempts to -solve this problem by providing a flexible system wide daemon which remaps keys -using kernel level input primitives (evdev, uinput). +Linux 缺少一套好用的按键重映射方案。要想获得满意的效果，往往需要组合使用多种工具（例如 xcape、xmodmap），而最终效果还常常绑定在特定环境（如 X11）上。keyd 试图通过提供一个灵活的全系统守护进程来解决这一问题；它利用内核级输入原语（evdev、uinput）来重映射按键。 -# Note on v2 +# 关于 v2 的说明 -The config format has undergone several iterations since the first -release. For those migrating their configs from v1 it is best -to reread the [man page](https://raw.githubusercontent.com/rvaiya/keyd/refs/heads/master/docs/keyd.scdoc) (`man keyd`). +自首次发布以来，配置格式已经历多次迭代。若要从 v1 迁移配置，最好重新阅读 [man page](https://raw.githubusercontent.com/rvaiya/keyd/refs/heads/master/docs/keyd.scdoc) (`man keyd`)。 -See also: [changelog](docs/CHANGELOG.md). +另请参阅：[changelog](docs/CHANGELOG.md)。 -# Goals +# 目标 - - Speed (a hand tuned input loop written in C that takes <<1ms) - - Simplicity (a [config format](#sample-config) that is intuitive) - - Consistency (modifiers that [play nicely with layers](https://github.com/rvaiya/keyd/blob/6dc2d5c4ea76802fd192b143bdd53b1787fd6deb/docs/keyd.scdoc#L128) by default) - - Modularity (a UNIXy core extensible through the use of an [IPC](https://github.com/rvaiya/keyd/blob/90973686723522c2e44d8e90bb3508a6da625a20/docs/keyd.scdoc#L391) mechanism) + - 速度 （用 C 编写、手工调优的输入循环，耗时 <<1ms） + - 简洁 （直观易懂的[配置格式](#sample-config)） + - 一致性 （修饰键默认就能与[层（layer）配合良好](https://github.com/rvaiya/keyd/blob/6dc2d5c4ea76802fd192b143bdd53b1787fd6deb/docs/keyd.scdoc#L128)） + - 模块化 （遵循 UNIX 哲学的核心，可通过 [IPC](https://github.com/rvaiya/keyd/blob/90973686723522c2e44d8e90bb3508a6da625a20/docs/keyd.scdoc#L391) 机制扩展） -# Features +# 特性 -keyd has several unique features many of which are traditionally only -found in custom keyboard firmware like [QMK](https://github.com/qmk/qmk_firmware) -as well as some which are unique to keyd. +keyd 拥有多项独特功能，其中许多传统上只出现在自定义键盘固件（如 [QMK](https://github.com/qmk/qmk_firmware)）中，也有一些是 keyd 独有的。 -Some of the more interesting ones include: +其中较有意思的有： -- Layers (with support for [hybrid modifiers](https://github.com/rvaiya/keyd/blob/6dc2d5c4ea76802fd192b143bdd53b1787fd6deb/docs/keyd.scdoc#L128)). -- Key overloading (different behaviour on tap/hold). -- Keyboard specific configuration. -- Instantaneous remapping (no more flashing :)). -- A client-server model that facilitates scripting and display server agnostic application remapping. (Currently ships with support for X, sway, and gnome (wayland)). -- System wide config (works in a VT). -- First class support for modifier overloading. -- Unicode support. +- 层（layer）（支持[混合修饰键（hybrid modifiers）](https://github.com/rvaiya/keyd/blob/6dc2d5c4ea76802fd192b143bdd53b1787fd6deb/docs/keyd.scdoc#L128)).） +- 按键过载（tap/hold 行为不同）。 +- 针对特定键盘的配置。 +- 即时重映射（无需再刷固件 :))。 +- 客户端-服务器模型，便于脚本化以及与显示服务器无关的应用重映射。（当前内置对 X、sway 和 gnome（Wayland）的支持。） +- 全系统配置（在 VT 中也可用）。 +- 对修饰键过载的一等支持。 +- Unicode 支持。 -### keyd is for people who: +### keyd 适合这些人： - - Would like to experiment with custom [layers](https://docs.qmk.fm/feature_layers) (i.e custom shift keys) - and oneshot modifiers. - - Want to have multiple keyboards with different layouts on the same machine. - - Want to be able to remap `C-1` without breaking modifier semantics. - - Want a keyboard config format which is easy to grok. - - Like tiny daemons that adhere to the Unix philosophy. - - Want to put the control and escape keys where God intended. - - Wish to be able to switch to a VT to debug something without breaking their keymap. + - 想尝试自定义[层（layer）](https://docs.qmk.fm/feature_layers)（即自定义 Shift 键） + 和 oneshot 修饰键。 + - 想在同一台机器上使用多台键盘、各自采用不同布局。 + - 希望能够重映射 `C-1`，同时不破坏修饰键语义。 + - 想要一种易于理解的键盘配置格式。 + - 喜欢遵循 Unix 哲学的小型守护进程。 + - 想把 Control 和 Escape 键放到它们本该在的位置。 + - 希望切换到 VT 调试问题时，不会弄乱自己的键位映射。 -### What keyd isn't: +### keyd 不是： - - A tool for programming individual key up/down events. + - 用于编程单个按键按下/抬起事件的工具。 -# Dependencies +# 依赖 - - Your favourite C compiler - - Linux kernel headers (already present on most systems) + - 你喜爱的 C 编译器 + - Linux 内核头文件（大多数系统上已自带） -## Optional +## 可选 - - python (for application specific remapping) - - python-xlib (only for X support) - - dbus-python (only for KDE support) + - python （用于应用特定重映射） + - python-xlib （仅用于 X 支持） + - dbus-python （仅用于 KDE 支持） -# Installation +# 安装 -*Note:* master serves as the development branch, things may occasionally break -between releases. Releases are [tagged](https://github.com/rvaiya/keyd/tags), and should be considered stable. +*注意：* master 作为开发分支，版本发布之间偶尔会有问题。发布版本已[打标签](https://github.com/rvaiya/keyd/tags),，可视为稳定版。 -## From Source +## 从源码安装 git clone https://github.com/rvaiya/keyd cd keyd make && sudo make install sudo systemctl enable --now keyd -# Quickstart +# 快速入门 -1. Install and start keyd (e.g `sudo systemctl enable keyd --now`) +1. 安装并启动 keyd（例如 `sudo systemctl enable keyd --now`） -2. Put the following in `/etc/keyd/default.conf`: +2. 将以下内容放入 `/etc/keyd/default.conf`： ``` [ids] @@ -100,34 +97,30 @@ capslock = overload(control, esc) esc = capslock ``` -Key names can be obtained by using the `keyd monitor` command. Note that while keyd is running, the output of this -command will correspond to keyd's output. The original input events can be seen by first stopping keyd and then -running the command. See the man page for more details. +可通过 `keyd monitor` 命令获取键名。请注意，在 keyd 运行期间，该命令的输出会对应 keyd 的输出。若要查看原始输入事件，需先停止 keyd，再运行该命令。更多细节请参阅 man page。 -3. Run `sudo keyd reload` to reload the config set. +3. 运行 `sudo keyd reload` 以重新加载配置。 -4. See the man page (`man keyd`) for a more comprehensive description. +4. 更完整的说明请参阅 man page（`man keyd`）。 -Config errors will appear in the log output and can be accessed in the usual -way using your system's service manager (e.g `sudo journalctl -eu keyd`). +配置错误会出现在日志输出中，也可通过系统的服务管理器以常规方式查看（例如 `sudo journalctl -eu keyd`）。 -*Note*: It is possible to render your machine unusable with a bad config file. -Should you find yourself in this position, the special key sequence -`backspace+escape+enter` should cause keyd to terminate. +*注意*：错误的配置文件可能使你的机器无法使用。 +若遇到这种情况，特殊按键序列 +`backspace+escape+enter` 应能让 keyd 终止运行。 -Some mice (e.g the Logitech MX Master) are capable of emitting keys and -are consequently matched by the wildcard id. It may be necessary to -explicitly blacklist these. +部分鼠标（例如 Logitech MX Master）能够发出按键事件， +因此会被通配符 id 匹配。可能需要显式将它们加入黑名单。 -## Application Specific Remapping (experimental) +## 应用特定重映射（实验性） -- Add yourself to the keyd group: +- 将自己加入 keyd 组： `usermod -aG keyd ` -- Populate `~/.config/keyd/app.conf`: +- 填写 `~/.config/keyd/app.conf`： -E.G +例如 [alacritty] @@ -139,39 +132,36 @@ E.G alt.[ = C-S-tab alt.] = macro(C-tab) -- Run: +- 运行： `keyd-application-mapper` -You will probably want to put `keyd-application-mapper -d` somewhere in your -display server initialization logic (e.g ~/.xinitrc) unless you are running Gnome. +你可能希望将 `keyd-application-mapper -d` 放在 +显示服务器初始化逻辑中的某处（例如 ~/.xinitrc），除非你运行的是 Gnome。 -See the man page for more details. +更多细节请参阅 man page。 -## SBC support +## SBC 支持 -Experimental support for single board computers (SBCs) via usb-gadget -has been added courtesy of Giorgi Chavchanidze. +在 Giorgi Chavchanidze 的贡献下，已通过 usb-gadget 为单板计算机（SBC）加入实验性支持。 -See [usb-gadget.md](src/vkbd/usb-gadget.md) for details. +详情请参阅 [usb-gadget.md](src/vkbd/usb-gadget.md)。 -## Packages +## 软件包 -Third-party packages exist for some distributions. If you wish to add -yours to the list please file a PR. These are kindly maintained by community -members, no personal responsibility is taken for them. +部分发行版已有第三方软件包。若希望将你的发行版加入列表，请提交 PR。这些软件包由社区成员好心维护，作者不对其承担个人责任。 ### Alpine Linux -[keyd](https://pkgs.alpinelinux.org/packages?name=keyd) package maintained by [@jirutka](https://github.com/jirutka). +[keyd](https://pkgs.alpinelinux.org/packages?name=keyd) 软件包由 [@jirutka](https://github.com/jirutka). 维护。 ### Arch -[Arch Linux](https://archlinux.org/packages/extra/x86_64/keyd/) package maintained by Arch packagers. +[Arch Linux](https://archlinux.org/packages/extra/x86_64/keyd/) 软件包由 Arch 打包者维护。 ### Debian -A keyd package is available in Debian 13 ("trixie") and later. To install: +Debian 13（"trixie"）及更高版本提供 keyd 软件包。安装方法： ```shell sudo apt install keyd @@ -179,36 +169,36 @@ sudo apt install keyd ### Fedora -[COPR](https://copr.fedorainfracloud.org/coprs/alternateved/keyd/) package maintained by [@alternateved](https://github.com/alternateved). +[COPR](https://copr.fedorainfracloud.org/coprs/alternateved/keyd/) 软件包由 [@alternateved](https://github.com/alternateved). 维护。 ### Gentoo -[GURU](https://gitweb.gentoo.org/repo/proj/guru.git/tree/app-misc/keyd) package maintained by [jack@pngu.org](mailto:jack@pngu.org). +[GURU](https://gitweb.gentoo.org/repo/proj/guru.git/tree/app-misc/keyd) 软件包由 [jack@pngu.org](mailto:jack@pngu.org) 维护。 ### openSUSE -[opensuse](https://software.opensuse.org//download.html?project=hardware&package=keyd) package maintained by [@bubbleguuum](https://github.com/bubbleguuum). +[opensuse](https://software.opensuse.org//download.html?project=hardware&package=keyd) 软件包由 [@bubbleguuum](https://github.com/bubbleguuum). 维护。 -Easy install with `sudo zypper in keyd`. +可使用 `sudo zypper in keyd` 轻松安装。 ### Ubuntu -A keyd package is available in Ubuntu 25.04 ("plucky") and later. To install: +Ubuntu 25.04（"plucky"）及更高版本提供 keyd 软件包。安装方法： ```shell sudo apt install keyd ``` -In addition, the latest Debian package backported to various Ubuntu releases can -be found in the [`ppa:keyd-team/ppa` +此外，可将最新 Debian 软件包反向移植到各 Ubuntu 版本，见 +[`ppa:keyd-team/ppa` archive](https://launchpad.net/~keyd-team/+archive/ubuntu/ppa). ### Void Linux -[xbps](https://github.com/void-linux/void-packages/tree/master/srcpkgs/keyd) package maintained by [@Barbaross](https://gitlab.com/Barbaross). +[xbps](https://github.com/void-linux/void-packages/tree/master/srcpkgs/keyd) 软件包由 [@Barbaross](https://gitlab.com/Barbaross). 维护。 -Easy install with `sudo xbps-install -Su keyd`. +可使用 `sudo xbps-install -Su keyd` 轻松安装。 -# Example 1 +# 示例 1 [ids] @@ -225,10 +215,10 @@ Easy install with `sudo xbps-install -Su keyd`. f = / ... -# Example 2 +# 示例 2 -This overrides specific alt combinations macOS users might -be more familiar with, while keeping the rest intact. +这会覆盖 macOS 用户可能更熟悉的一些特定 Alt 组合键， +同时保持其余映射不变。 [ids] * @@ -244,11 +234,10 @@ be more familiar with, while keeping the rest intact. r = C-r z = C-z -# Recommended config +# 推荐配置 -Many users will probably not be interested in taking full advantage of keyd. -For those who seek simple quality of life improvements I can recommend the -following config: +许多用户可能并不想充分利用 keyd 的全部能力。 +若你只想获得一些简单的生活质量改进，我推荐以下配置： [ids] @@ -266,26 +255,20 @@ following config: capslock = overload(control, esc) insert = S-insert -This overloads the capslock key to function as both escape (when tapped) and -control (when held) and remaps all modifiers to 'oneshot' keys. Thus to produce -the letter A you can now simply tap shift and then a instead of having to hold -it. Finally it remaps insert to S-insert (paste on X11). +该配置将 capslock 过载为：轻按作 escape，按住作 control； +并将所有修饰键重映射为 "oneshot" 键。因此，要输入字母 A， +你现在可以轻按 shift 再按 a，而不必一直按住 shift。 +最后，它将 insert 重映射为 S-insert（在 X11 上用于粘贴）。 -# FAQS +# 常见问题 -## Why is my trackpad is interfering with input after enabling keyd? +## 启用 keyd 后，触控板为何会干扰输入？ -libinput, a higher level input component used by most wayland and X11 setups, -includes a feature called 'disable-while-typing' that disables the trackpad -when typing. +libinput 是大多数 Wayland 和 X11 环境使用的高级输入组件，其中包含一项称为「打字时禁用」（disable-while-typing）的功能，可在打字时禁用触控板。 -In order to achieve this, it needs to distinguish between internal and external -keyboards, which it does by hard coding a rules for specific hardware -('quirks'). Since keyd creates a virtual device which subsumes both external -and integrated keyboards, you will need to instruct libinput to regard the keyd -virtual device as internal. +为实现这一点，它需要区分内置键盘与外接键盘，其做法是为特定硬件硬编码规则（称为 quirks）。由于 keyd 会创建一个虚拟设备，该设备同时涵盖外接键盘与集成键盘，因此你需要让 libinput 将 keyd 虚拟设备视为内置设备。 -This can be achieved by adding the following to `/etc/libinput/local-overrides.quirks` (which may need to be created): +可通过在 `/etc/libinput/local-overrides.quirks`（若不存在可能需要新建）中添加以下内容来实现： ``` [Serial Keyboards] @@ -295,41 +278,23 @@ MatchName=keyd*keyboard AttrKeyboardIntegration=internal ``` -Credit to @mark-herbert42 and @canadaduane for the original solution. +感谢 @mark-herbert42 和 @canadaduane 提供的原始解决方案。 -## What about xmodmap/setxkbmap/*? +## xmodmap/setxkbmap/* 呢？ -xmodmap and friends are display server level tools with limited functionality. -keyd is a system level solution which implements advanced features like -layering and [oneshot](https://docs.qmk.fm/#/one_shot_keys) -modifiers. While some X tools offer similar functionality I am not aware of -anything that is as flexible as keyd. +xmodmap 及其同类工具是显示服务器（display server）层面的工具，功能有限。keyd 是系统级方案，可实现分层（layering）和 [oneshot](https://docs.qmk.fm/#/one_shot_keys) 修饰键等高级功能。虽然部分 X 工具提供类似功能，但据我所知，没有哪款能像 keyd 这样灵活。 -## What about [kmonad](https://github.com/kmonad/kmonad)? +## [kmonad](https://github.com/kmonad/kmonad)? 呢？ -keyd was written several years ago to allow me to easily experiment with -different layouts on my growing keyboard collection. At the time kmonad did not -exist and custom keyboard firmware like -[QMK](https://github.com/qmk/qmk_firmware) (which inspired keyd) was the only -way to get comparable features. I became aware of kmonad after having published -keyd. While kmonad is a fine project with similar goals, it takes a different -approach and has a different design philosophy. +keyd 编写于数年前，目的是让我能在我不断扩充的键盘收藏上轻松试验不同布局。当时 kmonad 尚不存在，而像 [QMK](https://github.com/qmk/qmk_firmware)（启发 keyd 的自定义键盘固件）这类方案，是获得可比功能的唯一途径。发布 keyd 之后我才了解到 kmonad。kmonad 是一个目标相近的优秀项目，但采用了不同思路，设计哲学也不同。 -Notably keyd was written entirely in C with performance and simplicitly in -mind and will likely never be as configurable as kmonad (which is extensible -in Haskell). Having said that, it supplies (in the author's opinion) the -most valuable features in less than 2000 lines of C while providing -a simple language agnostic config format. +值得注意的是，keyd 完全用 C 编写，兼顾性能与简洁，很可能永远不会像 kmonad（可用 Haskell 扩展）那样可配置。话虽如此，在作者看来，它在不到 2000 行 C 代码内提供了最有价值的功能，并附带一种与语言无关的简单配置格式。 -## Why doesn't keyd implement feature X? +## 为什么 keyd 不实现功能 X？ -If you feel something is missing or find a bug you are welcome to file an issue -on github. keyd has a minimalist (but sane) design philosophy which -intentionally omits certain features (e.g execing arbitrary executables -as root). Things which already exist in custom keyboard firmware like QMK are -good candidates for inclusion. +如果你觉得缺少某些功能或发现了 bug，欢迎在 GitHub 上提交 issue。keyd 秉持极简（但合理）的设计哲学，有意省略某些功能（例如以 root 身份执行任意可执行文件）。像 QMK 这类自定义键盘固件中已有的功能，是较好的纳入候选。 -# Contributing +# 贡献 -See [CONTRIBUTING](CONTRIBUTING.md). -IRC Channel: #keyd on oftc +请参阅 [CONTRIBUTING](CONTRIBUTING.md)。 +IRC 频道：oftc 上的 #keyd