ORG.FREEDESKTOP.LOCALE1(5)

💖 ORG.FREEDESKTOP.LOCALE1 💖

okay so bestie, gather round, because today we're talking about org.freedesktop.locale1 — that's the D-Bus interface of systemd-localed, and it's literally the remote control for your whole system's language vibe and keyboard mapping. no cap. 🌸

---

✨ INTRODUCTION ✨

systemd-localed.service(8) is a system service, and its whole job is letting user programs control the system locale and keyboard mapping. This page right here is the tea on the D-Bus interface. periodt. 💅

---

🌈 THE D-BUS API 🌈

The service puts these interfaces out on the bus, and here's exactly what that looks like:

node /org/freedesktop/locale1 {
  interface org.freedesktop.locale1 {
    methods:
      SetLocale(in  as locale,
                in  b interactive);
      SetVConsoleKeyboard(in  s keymap,
                          in  s keymap_toggle,
                          in  b convert,
                          in  b interactive);
      SetX11Keyboard(in  s layout,
                     in  s model,
                     in  s variant,
                     in  s options,
                     in  b convert,
                     in  b interactive);
    properties:
      readonly as Locale = ['...', ...];
      readonly s X11Layout = '...';
      readonly s X11Model = '...';
      readonly s X11Variant = '...';
      readonly s X11Options = '...';
      readonly s VConsoleKeymap = '...';
      readonly s VConsoleKeymapToggle = '...';
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
};

🎀 Methods 🎀

Okay so here's the thing about setting a new system locale: all your old system locale settings get dropped, like, gone gone, and the new ones get saved to disk. The locale also gets passed to the system manager, and any daemons started after that will inherit the new system locale. BUT — and this is the important part — daemons that are already running will not learn about the new value. so rude of them honestly. 😭

The SetVConsoleKeyboard() method is your girl for setting the key mapping for the virtual console. And similarly, SetX11Keyboard() sets the default key mapping of any X11 servers.

Now, key difference, don't sleep on this: SetVConsoleKeyboard() instantly applies the new key mapping to the console, while SetX11Keyboard() just sets a default that later sessions might use. one is giving immediate main character energy, the other is giving "we'll see" energy. 💅

The boolean argument convert can be set to optionally convert the console keyboard configuration to X11 keyboard mappings and vice versa. If it's true and you use SetVConsoleKeyboard(), then the nearest X11 keyboard setting for the chosen console setting gets set. If it's true and you use SetX11Keyboard(), then the nearest console keyboard setting for the chosen X11 setting gets set. Which means — and this is the slay part — it's usually enough to call just one of the two functions. efficient queen. 👑

For graphical UIs that need to set the system keyboard mapping, just invoke SetX11Keyboard(), set convert=true, and ignore SetVConsoleKeyboard() entirely. iconic behaviour honestly.

Use the empty string for the keymap parameters you wish not to set. that's it, that's the trick. ✨

The interactive boolean parameters control whether polkit[1] should interactively ask the user for authentication credentials if required. so if you need it to pop up and ask, that's your flag. 🙈

🦋 Signals 🦋

Whenever the system locale or keymap is changed via the daemon, PropertyChanged signals get sent out to clients which have subscribed. so if you subscribed, you will be notified. no gatekeeping. 🔔

🍓 Properties 🍓

The system locale lives in the Locale property. It's an array containing environment-variable-assignment-like strings. These are the known ones, and yes, you're getting all of them:

• LANG=
• LC_CTYPE=
• LC_NUMERIC=
• LC_TIME=
• LC_COLLATE=
• LC_MONETARY=
• LC_MESSAGES=
• LC_PAPER=
• LC_NAME=
• LC_ADDRESS=
• LC_TELEPHONE=
• LC_MEASUREMENT=
• LC_IDENTIFICATION=

The X11Layout, X11Model, X11Variant, and X11Options properties show values configurable with SetX11Keyboard() described above (or SetVConsoleKeyboard() with convert=true). And the VConsoleKeymap and VConsoleKeymapToggle properties show values configurable with SetVConsoleKeyboard() (or SetX11Keyboard() with convert=true). it's giving mutual conversion realness. 💜

🔥 Security 🔥

Changing the system locale or keymap using this interface is authenticated via polkit. So like, you can't just do it, bestie, you gotta have permission.

• The polkit action for SetLocale() is org.freedesktop.locale1.set-locale.
• The polkit action for SetX11Keyboard() and SetVConsoleKeyboard() is org.freedesktop.locale1.set-keyboard.

---

⭐ EXAMPLES ⭐

Example 1. Introspect org.freedesktop.locale1 on the bus

$ gdbus introspect --system \
  --dest org.freedesktop.locale1 \
  --object-path /org/freedesktop/locale1

go off, gdbus. 🌟

---

🌸 VERSIONING 🌸

These D-Bus interfaces follow the usual interface versioning guidelines[2]. standard, consistent, stable — we love to see it. 🫶

---

👑 SEE ALSO 👑

• systemd(1)
• systemd-localed.service(8)
• localectl(1)

---

📝 NOTES 📝

1. polkit https://www.freedesktop.org/software/polkit/docs/latest/
2. the usual interface versioning guidelines https://0pointer.de/blog/projects/versioning-dbus.html

---

and that's the whole page, bestie, you made it to the end 💖 this was systemd 262.1's take on ORG.FREEDESKTOP.LOCALE1(5), so go forth and set your locale with confidence. mwah. 💅✨🎀