# localization

Locale, time zone and console keymap as one module (novox/hq to-be 42 Phase 1, research 027: the
operator's choice of one module for the three).

## What it owns

- `/etc/locale.conf`, written whole: `LANG=en_US.UTF-8`. It takes effect at the next login.
- `/etc/vconsole.conf`, written whole: `KEYMAP=us`. It takes effect at the next boot.
- The time zone, `Europe/Brussels`, through a **step**. The host runs the module's own binary once
  per version of the bundle, as root: `localization-tools set-time-zone Europe/Brussels`. The step
  asks the time daemon (`timedatectl set-timezone`) only when the zone differs, and reads it back.

## Why the time zone is a step

`/etc/localtime` is a symbolic link into the zone database, and the mesh writes no symbolic links
(ADR 0012). A copy of the zone file written there works for the C library, but timedatectl and
everything else that reads the zone's *name* from the link then answers `n/a`. A module may not
declare an action (ADR 0005). The step makes no link itself: the distribution's own time daemon keeps
its link, and the step's answer is read back.

The trade-off: the step runs again only when the bundle changes, not at every push. A zone changed
by hand stays changed until then. `localization_get` shows it as not as declared.

## What it improves

One machine was on another time zone (the same offset, a different name) with a German console
keymap, and nothing recorded why. Every machine is now the same.

## What it leaves found

- `/etc/locale.gen` and the generated locales. `en_US.UTF-8` was generated on all four machines on
  2026-10-04, so the module checks it (`lang_generated`) and does not generate it.
- X11's keyboard settings, which belong to the display server's module (research 026).

On a machine whose `/etc/locale.conf` carried more than `LANG` (one workstation also had
`LANGUAGE=en_US`), the extra line goes. `LANG` alone means the same.

## Tools

| tool | | answers |
|---|---|---|
| `localization_get` | r | LANG and every `LC_*`, whether LANG is generated, the zone, whether the RTC keeps local time, NTP on and synchronised, the console keymap, X11 keyboard, and `as_declared` for each of the three |
| `localization_time_zone` | r/a | the zone; the zones matching a word; or `set` one (sudo -n timedatectl, read back) |
| `localization_locales` | r | generated, enabled in `locale.gen`, LANG and whether it is generated, and the locales glibc can generate (listed when narrowed) |
| `localization_keymaps` | r | the keymap in force and the keymaps available, narrowed to a word |