https://github.com/joelspadin/zmk-locales
Helpers for localizing ZMK keymaps
https://github.com/joelspadin/zmk-locales
zmk zmk-module
Last synced: about 1 year ago
JSON representation
Helpers for localizing ZMK keymaps
- Host: GitHub
- URL: https://github.com/joelspadin/zmk-locales
- Owner: joelspadin
- License: mit
- Created: 2024-09-15T17:24:05.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-06-22T23:37:16.000Z (about 1 year ago)
- Last Synced: 2025-06-23T00:31:04.660Z (about 1 year ago)
- Topics: zmk, zmk-module
- Language: C
- Homepage:
- Size: 288 KB
- Stars: 17
- Watchers: 1
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ZMK Locales
This is a [module for ZMK](https://zmk.dev/docs/features/modules) which helps with creating keymaps for non-US keyboard layouts.
Many of the files in this repo are generated by [ZMK Locale Generator](https://github.com/joelspadin/zmk-locale-generator). Pull requests to update any files in the "include" subfolder will not be accepted, because the changes would just get overwitten the next time I re-generate them. Please submit pull requests to the locale generator instead.
## Usage
See the [ZMK module documentation](https://zmk.dev/docs/features/modules#building-with-modules) for instructions on how to add this module to your firmware build. Once it is added to the build, you can use the features described below:
### Key Codes
ZMK's key codes follow the [HID specification](https://www.usb.org/hid), and many key codes indicate the *position* of a key on a US keyboard layout, not the key's function. If your operating system (OS) is set to a different keyboard locale, then the character a key types may not match its key code name. For example, on a German QWERTZ layout, `&kp Y` will type z and `&kp Z` will type y. This module provides headers with localized key codes, so instead of having to remember that `Y` is `Z` and `Z` is `Y`, you can just include the German header and use `DE_Y` and `DE_Z`.
First, find the header that matches your OS keyboard layout inside the [include/locale](include/locale) folder. Each file starts with a comment that gives the full name of the keyboard layout.
Next, include it at the top of your keymap like this. The path inside the `#include <...>` is the path to the header relative to the `/include` folder in this repo.
```dts
#include
/ {
keymap {
...
};
};
```
Finally, look inside the header to see what key codes it provides, and use these key codes in your keymap instead of the standard ZMK key codes.
For example, this snippet of [keys_de.h](include/locale/keys_de.h)...
```c
/* y */
#define DE_Y (ZMK_HID_USAGE(HID_USAGE_KEY, HID_USAGE_KEY_KEYBOARD_Z))
/* z */
#define DE_Z (ZMK_HID_USAGE(HID_USAGE_KEY, HID_USAGE_KEY_KEYBOARD_Y))
```
...says you can use `DE_Y` for y and `DE_Z` for z, while this one...
```c
/* ß */
#define DE_SHARP_S (ZMK_HID_USAGE(HID_USAGE_KEY, HID_USAGE_KEY_KEYBOARD_MINUS_AND_UNDERSCORE))
#define DE_ESZETT (DE_SHARP_S)
#define DE_SZ (DE_SHARP_S)
```
...says you can use `DE_SHARP_S`, `DE_ESZETT`, or `DE_SZ` for ß.
A keymap using these localized key codes might look like this:
```dts
#include
/ {
keymap {
compatible = "zmk,keymap";
default_layer {
bindings = <
&kp DE_CARET &kp DE_N1 &kp DE_N2 &kp DE_N3 &kp DE_N4 &kp DE_N5 &kp DE_N6 ...
&kp TAB &kp DE_Q &kp DE_W &kp DE_E &kp DE_R &kp DE_T &kp DE_Z ...
&kp CAPS &kp DE_A &kp DE_S &kp DE_D &kp DE_F &kp DE_G &kp DE_H ...
&kp LSHFT &kp DE_LT &kp DE_Y &kp DE_X &kp DE_C &kp DE_V &kp DE_B &kp DE_N ...
&kp LCTRL &kp LGUI &kp LALT &kp DE_SPACE ...
>;
};
};
};
```