Locale & Keyboard

Concepts: Locale vs. Keyboard vs. Fonts

These are three independent systems. Conflating them is common but wrong.

System What It Controls When You Need to Change It

Locale

Date/time formats, number formatting, currency symbols, sort order, character classification

Almost never. en_US.UTF-8 already supports every script (Hebrew, Arabic, CJK, Cyrillic). You only need a different locale if you want system-level formatting in another language (e.g., dates in Hebrew format).

Keyboard Layout

Which physical key produces which character. us = QWERTY English, es = Spanish (ñ, accent dead keys), il = Hebrew (remaps keys to alef-bet)

When you need to type in another script. Multiple layouts can coexist with a toggle key.

Fonts

Whether your terminal/browser can render the glyphs. A font must contain the Unicode codepoints for the script.

When you see boxes (□□□) instead of characters. Install a font covering that script.

The key insight: UTF-8 is a character encoding, not a language. Your en_US.UTF-8 locale can store, display, grep, and pipe Hebrew, Arabic, Japanese — any Unicode text — without changing anything. Locale only affects formatting (is the decimal separator . or ,?), not character support.

Locale

Current State

Show system locale, console keymap, and X11 layout
localectl status
Output (typical Arch setup)
System Locale: LANG=en_US.UTF-8
    VC Keymap: (unset)
   X11 Layout: (unset)
List all generated locales
locale -a
Show all locale categories in detail
locale

Locale Categories

Each category controls a different formatting aspect. All inherit from LANG unless overridden.

Variable Controls

LANG

Master default — all categories inherit from this

LC_COLLATE

Sort order (affects sort, ls, filename ordering)

LC_CTYPE

Character classification (upper/lower, alpha/digit — critical for regex)

LC_MESSAGES

System message language (error messages, man pages)

LC_NUMERIC

Number formatting (. vs , for decimals)

LC_TIME

Date/time format

LC_MONETARY

Currency formatting

LC_ALL

Nuclear override — overrides ALL categories. Use sparingly.
Override one category without changing everything
# Spanish date formatting, everything else English
export LC_TIME=es_ES.UTF-8

Generate a New Locale

Enable a locale — uncomment in locale.gen, then regenerate
# Before
sudo awk '/^#he_IL.UTF-8/' /etc/locale.gen

# Change
sudo sed -i 's/^#he_IL.UTF-8/he_IL.UTF-8/' /etc/locale.gen
sudo locale-gen

# After
locale -a | grep he_IL
Output
he_IL.utf8
Common locales to enable for multilingual work
# Uncomment all at once
sudo sed -i 's/^#\(en_US.UTF-8\)/\1/; s/^#\(es_ES.UTF-8\)/\1/; s/^#\(he_IL.UTF-8\)/\1/' /etc/locale.gen
sudo locale-gen
You do NOT need to generate he_IL to read, grep, or display Hebrew. en_US.UTF-8 handles all Unicode. Generate it only if you want Hebrew-formatted dates/numbers.

Keyboard Layouts

How XKB Works

XKB (X Keyboard Extension) is the layout system used by both X11 and Wayland compositors. Key concepts:

Term Meaning

Layout

The base character mapping (us, es, il, ara, ru, de)

Variant

A sub-layout within a layout (us has dvorak, colemak; il has biblical for nikkud input)

Options

Behavior modifiers — most important is the layout toggle key

Model

Physical keyboard model (pc105 for standard 105-key)

List Available Layouts

Show all available XKB layouts
localectl list-x11-keymap-layouts
Show variants for a specific layout
localectl list-x11-keymap-variants il
Show available toggle options
localectl list-x11-keymap-options | grep grp:
Output (common toggle options)
grp:alt_shift_toggle    — Alt+Shift (current config)
grp:win_space_toggle    — Super+Space (macOS style)
grp:ctrl_shift_toggle   — Ctrl+Shift
grp:caps_toggle         — Caps Lock
grp:ralt_toggle         — Right Alt alone
grp:lalt_toggle         — Left Alt alone
grp:toggle              — Right Alt (legacy)

Hyprland (Your Setup)

Your Hyprland config at ~/.config/hypr/hyprland.conf line 118-120:

Current keyboard configuration
input {
    kb_layout = us,es
    kb_options = grp:alt_shift_toggle
}

This gives you US and Spanish, toggled with Alt+Shift.

Add Hebrew — just append to the layout list
input {
    kb_layout = us,es,il
    kb_options = grp:alt_shift_toggle
}

Alt+Shift now cycles: us → es → il → us.

Reload Hyprland config (no restart needed)
hyprctl reload
Check which layout is currently active
hyprctl devices -j | jq '.keyboards[] | {name, active_keymap}'
Switch layout programmatically
# Next layout
hyprctl switchxkblayout all next

# Specific layout by index (0=us, 1=es, 2=il)
hyprctl switchxkblayout all 2

Layout Variants

Hebrew Biblical variant — includes nikkud input
input {
    kb_layout = us,es,il
    kb_variant = ,,biblical
    kb_options = grp:alt_shift_toggle
}

The ,,biblical means: no variant for us, no variant for es, biblical variant for il.

Session-Only Testing (no config edit)

Test a layout temporarily with setxkbmap
setxkbmap -layout us,es,il -option grp:alt_shift_toggle
Verify
setxkbmap -query
Reset to single US layout
setxkbmap -layout us -option ""

Sway

Add to ~/.config/sway/config
input type:keyboard {
    xkb_layout us,es,il
    xkb_options grp:alt_shift_toggle
}
Reload
swaymsg reload

Console (TTY)

Set console keymap (limited — no Hebrew in TTY)
sudo localectl set-keymap us
Hebrew input in TTY requires kbd package and a Hebrew console keymap. For practical terminal scripture work, grep from existing text files — no Hebrew typing needed.

Fonts

Check Font Coverage for a Script

List fonts supporting Hebrew
fc-list :lang=he
List fonts supporting Arabic
fc-list :lang=ar
List fonts supporting Japanese
fc-list :lang=ja

Install Fonts

Noto fonts — covers nearly every script (recommended)
sudo pacman -S noto-fonts noto-fonts-extra noto-fonts-cjk noto-fonts-emoji
Package Covers

noto-fonts

Latin, Greek, Cyrillic (base)

noto-fonts-extra

Hebrew, Arabic, Thai, Devanagari, and 100+ other scripts

noto-fonts-cjk

Chinese, Japanese, Korean

noto-fonts-emoji

Emoji
Verify after install
fc-list :lang=he | head -5
Rebuild font cache (usually automatic)
fc-cache -fv

Terminal Font Fallback

Your terminal emulator font (e.g., JetBrainsMono Nerd Font) likely doesn’t contain Hebrew glyphs. That’s fine — modern terminals fall back to system fonts.

Terminal Fallback Behavior

Ghostty

Automatic fallback via fontconfig

Kitty

Automatic, or set symbol_map in kitty.conf

Alacritty

Automatic fallback via fontconfig

foot

Automatic fallback
Test if your terminal renders Hebrew with nikkud
echo "בְּרֵאשִׁית בָּרָא אֱלֹהִים"

If you see the Hebrew text with vowel points below the consonants, your font setup is correct.

Practical: Adding a New Language

Complete workflow — adding Hebrew to an Arch/Hyprland system
# 1. Install fonts (if Hebrew renders as boxes)
sudo pacman -S noto-fonts-extra

# 2. Add keyboard layout to Hyprland
sed -i 's/kb_layout = us,es/kb_layout = us,es,il/' ~/.config/hypr/hyprland.conf
hyprctl reload

# 3. (Optional) Generate locale for Hebrew date formatting
sudo sed -i 's/^#he_IL.UTF-8/he_IL.UTF-8/' /etc/locale.gen
sudo locale-gen

# 4. Verify
fc-list :lang=he | head -1
hyprctl devices -j | jq '.keyboards[0].active_keymap'
echo "בְּרֵאשִׁית — Test"
Adding Arabic
# Fonts: already covered by noto-fonts-extra
# Layout: add 'ara' to kb_layout
sed -i 's/kb_layout = us,es,il/kb_layout = us,es,il,ara/' ~/.config/hypr/hyprland.conf
hyprctl reload
Adding Japanese (needs input method for kanji)
sudo pacman -S noto-fonts-cjk fcitx5 fcitx5-mozc fcitx5-gtk fcitx5-qt fcitx5-configtool
# Then configure fcitx5 — XKB alone only handles kana, not kanji conversion
Latin-script languages (Spanish, French, German) and right-to-left scripts (Hebrew, Arabic) work fine with just XKB layout switching. CJK languages (Chinese, Japanese, Korean) need an input method framework (fcitx5 or ibus) because they require character composition.

System Documentation

Linux documentation lives in five places. Knowing which to check first saves time.

Source What It Contains How to Access

man pages

Command usage, config file format, system call reference. Organized by section (1=commands, 5=file formats, 7=concepts).

man <topic>, man -k <keyword> to search, man -w <topic> to check if it exists

info pages

Extended documentation with chapters, cross-references. GNU projects use these (glibc, coreutils). Often more detailed than man pages.

info <topic>, navigate with n/p/u/Enter

/usr/share/doc/

Package-specific docs, HTML references, READMEs, changelogs. Installed by packages.

ls /usr/share/doc/<package>/

System config files

The files themselves are documentation. Read them — they have comments explaining every option.

/etc/locale.gen, /etc/locale.conf, /etc/vconsole.conf

Data files

XKB layout definitions, fontconfig configs, keymap files. Readable source that defines behavior.

/usr/share/X11/xkb/, /etc/fonts/, /usr/share/kbd/keymaps/

Man Pages (verified on this system)

Locale & Character Sets

How locale works — categories, environment variables, encoding
man locale              # (1) Overview of locale categories and environment variables
man locale.conf         # (5) systemd locale config file — /etc/locale.conf format
man localectl           # (1) systemd tool to query and set locale + keyboard
man charsets            # (7) Character set standards — ASCII, ISO-8859, UTF-8 history
man utf-8               # (7) UTF-8 encoding — how multi-byte characters work
man unicode             # (7) Unicode standard — code points, planes, BMP
locale-gen has no man page on Arch. It’s a simple script: reads /etc/locale.gen, generates compiled locales in /usr/lib/locale/. Read it directly: cat $(which locale-gen).

Keyboard / XKB

Keyboard layout system — configuration and data
man xkeyboard-config    # (7) MASTER REFERENCE — every layout, variant, and option
man setxkbmap           # (1) Set XKB layout from command line
man xkbcomp             # (1) Compile XKB keymap — advanced, rarely needed directly

Fonts / Fontconfig

Font selection, matching, and caching
man fc-list             # (1) List fonts — filter by :lang=, :family=, :style=
man fc-match            # (1) Show which font the system selects for a pattern
man fc-cache            # (1) Rebuild font cache after installing new fonts
man fc-cat              # (1) Dump font cache contents
man fc-pattern          # (1) Font pattern syntax — how filter expressions work
man fonts-conf          # (5) Fontconfig configuration — /etc/fonts/fonts.conf format

Hyprland

Compositor and IPC control
man Hyprland            # (1) General overview — note capital H
man hyprctl             # (1) IPC control — keyword, dispatch, devices, clients
Test keyboard config changes live without editing the config file
hyprctl keyword input:kb_layout us,es,il
hyprctl devices -j | jq '.keyboards[] | {name, active_keymap}'

Info Pages

The GNU C Library (glibc) info manual has a full chapter on locales — deeper than the man pages.

Read the glibc locale chapter
info libc 'Locales'

This covers: locale categories in detail, how setlocale() works, locale data format, and how programs use locale settings internally. Worth reading once to understand why locale exists, not just how to set it.

Navigate info pages
n         — next node
p         — previous node
u         — up one level
Enter     — follow a cross-reference
l         — go back
q         — quit

System Config Files

These files ARE the documentation for your current state. Read them.

Locale configuration chain
cat /etc/locale.gen     # Which locales are enabled (uncommented lines)
cat /etc/locale.conf    # System default locale (LANG=en_US.UTF-8)
cat /etc/vconsole.conf  # Console keymap (TTY, not Wayland)
Hyprland keyboard config (YOUR current state)
grep -A5 'kb_layout' ~/.config/hypr/hyprland.conf

Data Files (The Real Source of Truth)

XKB Layout Data

Everything XKB knows about keyboard layouts lives in /usr/share/X11/xkb/. These are plain text files — readable and greppable.

Directory structure
/usr/share/X11/xkb/
├── symbols/     # Layout definitions — one file per language
├── rules/       # Mapping rules and the greppable index
├── keycodes/    # Physical key → keycode mapping
├── types/       # Key type definitions (shift behavior)
├── compat/      # Compatibility mappings
└── geometry/    # Physical keyboard geometry (rarely needed)
Read the Hebrew keyboard layout definition
cat /usr/share/X11/xkb/symbols/il

This shows exactly which physical key produces which Hebrew character — the source of truth for the il layout.

Read the Spanish layout
cat /usr/share/X11/xkb/symbols/es
Grep the master index for all layout toggle options
grep 'grp:' /usr/share/X11/xkb/rules/evdev.lst
Output (partial)
grp:alt_shift_toggle     Alt+Shift
grp:win_space_toggle     Win+Space
grp:ctrl_shift_toggle    Ctrl+Shift
grp:caps_toggle          Caps Lock
grp:ralt_toggle          Right Alt
List all available layouts
grep '^\s' /usr/share/X11/xkb/rules/evdev.lst | head -30
List all variants for Hebrew
grep -A1 '^\s*il' /usr/share/X11/xkb/rules/evdev.lst | grep 'il:'
Or use localectl (wraps the same data)
localectl list-x11-keymap-layouts          # All layouts
localectl list-x11-keymap-variants il      # Hebrew variants
localectl list-x11-keymap-options | grep grp:  # Toggle options

Fontconfig Data

Main fontconfig configuration
cat /etc/fonts/fonts.conf           # Global config (usually points to conf.d/)
ls /etc/fonts/conf.d/               # Active config fragments (symlinks)
ls /usr/share/fontconfig/conf.avail/ # Available config fragments
Package-shipped HTML documentation
# Fontconfig developer and user guides
ls /usr/share/doc/fontconfig/
# fontconfig-user.html  — end-user configuration guide
# fontconfig-devel.html — developer API reference

Open in browser: firefox /usr/share/doc/fontconfig/fontconfig-user.html

Console Keymaps (TTY)

Hebrew console keymaps (for TTY, not Wayland)
ls /usr/share/kbd/keymaps/i386/qwerty/il*
Output
/usr/share/kbd/keymaps/i386/qwerty/il-heb.map.gz
/usr/share/kbd/keymaps/i386/qwerty/il-phonetic.map.gz
/usr/share/kbd/keymaps/i386/qwerty/il.map.gz
Load a console keymap temporarily (TTY only)
sudo loadkeys il

Web References

Topic URL

Locale (Arch Wiki)

wiki.archlinux.org/title/Locale

Keyboard — Console

wiki.archlinux.org/title/Linux_console/Keyboard_configuration

Keyboard — Xorg/XKB

wiki.archlinux.org/title/Xorg/Keyboard_configuration

Hyprland Input Config

wiki.hyprland.org/Configuring/Variables/#input

Fonts (Arch Wiki)

wiki.archlinux.org/title/Fonts

Font Configuration

wiki.archlinux.org/title/Font_configuration

Fcitx5 (CJK input)

wiki.archlinux.org/title/Fcitx5

Unicode Code Charts

unicode.org/charts/

Unicode CLDR

www.unicode.org/cldr/
Install arch-wiki-docs for offline access: sudo pacman -S arch-wiki-docs. Then browse at /usr/share/doc/arch-wiki/html/.