Inspect and Change Locale Settings through org.freedesktop.locale1

You will inspect the system locale and keyboard settings exposed by systemd-localed, then have a safe pattern for changing one setting through D-Bus and checking the result. Allow about fifteen minutes. You need a Linux system running systemd-localed, the gdbus or busctl utility, and permission to authenticate through polkit for changes.

This guide describes the interface installed here with systemd 255.4-1ubuntu8.17, whose manpage identifies the interface as org.freedesktop.locale1. Your distribution may package another systemd release, so inspect its local manpage before putting these calls in automation.

1. Check the service and interface name

Start with read-only checks. These do not need elevated privileges:

$ command -v gdbus
/usr/bin/gdbus
$ systemctl status systemd-localed.service --no-pager
$ systemctl --version
systemd 255

The D-Bus destination is org.freedesktop.locale1, and its object path is /org/freedesktop/locale1. The service may be activated on demand, so an inactive status is not by itself proof that the interface is unusable.

Checkpoint: ask the system bus what the service publishes:

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

Look for the org.freedesktop.locale1 interface, the three methods, and the read-only properties. If this reports that the bus or destination is unavailable, stop there and investigate systemd-localed or the machine's D-Bus setup. Do not switch to the session bus: this is a system service.

2. Capture the current state

Read the properties before changing anything. busctl prints the D-Bus type followed by the value; an array such as Locale can contain several environment assignments.

$ busctl get-property org.freedesktop.locale1 \
  /org/freedesktop/locale1 org.freedesktop.locale1 Locale
as 1 "LANG=en_US.UTF-8"
$ busctl get-property org.freedesktop.locale1 /org/freedesktop/locale1 \
  org.freedesktop.locale1 X11Layout
s "us"
$ busctl get-property org.freedesktop.locale1 /org/freedesktop/locale1 \
  org.freedesktop.locale1 VConsoleKeymap
s ""

Your values will differ. Record every locale assignment and keyboard property you may need to restore. The useful properties are Locale, X11Layout, X11Model, X11Variant, X11Options, VConsoleKeymap, and VConsoleKeymapToggle.

3. Change the system locale deliberately

Changing locale is a persistent system change. It writes the new locale settings to disk and passes them to the system manager, but already-running daemons do not learn the new value. Save the old value first, and warn anyone using the machine before changing a shared host.

Replace the example locale with one installed and supported on your host. The call uses an array of assignment strings and a final boolean controlling interactive polkit authentication:

$ gdbus call --system \
  --dest org.freedesktop.locale1 \
  --object-path /org/freedesktop/locale1 \
  --method org.freedesktop.locale1.SetLocale \
  "['LANG=en_GB.UTF-8']" true

A successful D-Bus call normally returns an empty tuple, shown as (). The true permits an authentication prompt if polkit requires one. Use false for a non-interactive caller that should fail rather than prompt.

Verify the result and remember that a new process is needed to observe the environment:

$ busctl get-property org.freedesktop.locale1 \
  /org/freedesktop/locale1 org.freedesktop.locale1 Locale
$ locale

To undo this change, call SetLocale again with the complete assignment array you recorded. Supplying a new locale replaces the old system locale settings; it is not an additive edit.

4. Change keyboard defaults with conversion enabled

The graphical keyboard method is usually the practical entry point. SetX11Keyboard takes layout, model, variant, options, a conversion flag, and the polkit interaction flag. Empty strings mean that a parameter is not being set.

This example sets a US layout and asks systemd-localed to derive the nearest virtual-console mapping:

$ gdbus call --system \
  --dest org.freedesktop.locale1 \
  --object-path /org/freedesktop/locale1 \
  --method org.freedesktop.locale1.SetX11Keyboard \
  us pc105 "" "" true true

Check all related properties after the call:

$ busctl introspect org.freedesktop.locale1 /org/freedesktop/locale1 \
  org.freedesktop.locale1
$ localectl status

Restore the recorded layout, model, variant, options, and console values with the corresponding method if the result is wrong. Use empty strings only for fields you intentionally want to leave unset. A polkit denial is an authorisation problem, not a reason to run the command repeatedly as root.

5. Monitor changes and diagnose failures

Clients can subscribe to D-Bus property-change signals. For a short observation window, use:

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

Run the read or change in another terminal, then stop the monitor with Ctrl-C. A property signal confirms that the daemon announced a change, not that an already-running daemon has reloaded its environment.

If a method fails, check the method signature from introspection, the destination bus, and polkit logs. Common mistakes are using the session bus, omitting the array brackets for SetLocale, passing keyboard arguments in the wrong order, and assuming that an empty property means the host has no keyboard configuration. Avoid debugging by applying guessed settings to a production console.