locale
A locale is the set of language settings that programs use for messages,
dates, and sorting, such as en_US.UTF-8. locale makes one locale
available on the node and says whether it is the system default. Write one
node task for each locale the node needs.
Set up
On the Red Hat family, locales come in packages, one for each language:
glibc-langpack-<language>, such as glibc-langpack-de for de_DE.UTF-8.
Install the package in an earlier node task:
- dnf_package:
packages:
- {name: glibc-langpack-de, version: newest_when_first_installed}
- locale:
name: de_DE.UTF-8
use_as_system_default: true
On Debian and Ubuntu, locale-gen and update-locale come from the package
locales, which server images usually have. A missing program fails the
node task, and the reason names its package.
Inputs
name(string; required): such as en_US.UTF-8; on Debian and Ubuntu a missing locale gets its line in /etc/locale.gen enabled and locale-gen makes it; on the Red Hat family a missing locale fails and names the packageglibc-langpack-<language>to install first with dnf_packageuse_as_system_default(boolean; required): true sets LANG of the system locale (update-locale on Debian and Ubuntu, localectl on the Red Hat family) and keeps its other settings; false leaves the system default alone
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschangevalue.made_availablevalue.system_default_beforevalue.system_default_after
What a dryrun reports
Supported; reports whether the locale would be made and the system default that would be set; a missing glibc-langpack package is not checked, because an earlier task may install it.
Retries and time limits
Bounded automatic retries by default; retry: false turns them off.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
Make a locale the system default
- locale:
name: en_US.UTF-8
use_as_system_default: true
On the node, this node task makes the locale en_US.UTF-8 available and
makes it the system default. MMX inspects the node first and reports
unchanged when the node already matches.
How it works
nameis a locale name, such asen_US.UTF-8orde_DE.UTF-8.use_as_system_defaultis required. Withtrue, MMX setsLANGof the system locale to the locale named byname. Withfalse, MMX leaves the system default alone.- Debian and Ubuntu make locales from the list in
/etc/locale.gen. When the locale is missing, MMX enables its line there and runslocale-gen. When the file has no line for it, MMX adds the line from/usr/share/i18n/SUPPORTED. A name that neither file lists fails before any change, so a misspelled name never reaches the node. - The Red Hat family installs locales in packages. When the locale is
missing, the node task fails and names the package to install first with
dnf_package; see Set up. - With
use_as_system_default: true, MMX setsLANGwithupdate-localeon Debian and Ubuntu, which writes/etc/default/locale, and withlocalectlon the Red Hat family. The other settings of the system locale, such asLC_TIME, stay as they are. - Results and dryrun show what changes in
.this_node_task.value:made_available: truewhen the locale was made, andsystem_default_beforeandsystem_default_afterwhenLANGchanged. A run that fails lists only what it did before the failure, so a node task inon_failurecan read what happened. - Running services read the locale when they start. A change does not restart them; restart a service that must follow the change on purpose, for example from a restart playbook.
Errors and what they mean
| The reason holds | What the error means, and what to do |
|---|---|
locale de_DE.UTF-8 is not installed; install the package glibc-langpack-de first with dnf_package |
On the Red Hat family, the locale's package is missing. Install it in an earlier node task; see Set up. A dryrun reports the node task not checked, because an earlier node task may install the package. |
this node cannot make locale ...: neither /etc/locale.gen nor /usr/share/i18n/SUPPORTED lists it; check the spelling, such as en_US.UTF-8 |
On Debian and Ubuntu, the name is not a locale that the node can make. Check the spelling. Nothing was changed. |
locale-gen is not installed; install the package ... first |
A program that the module runs is missing: localectl, locale-gen, or update-locale. The reason names the package. Install it in an earlier node task. A dryrun reports the node task not checked. |
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.
The suite tests/integration/node_settings.py runs on Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10, in containers on the first four and in virtual machines on the last two. The
validation record
has the latest results.
Why it works this way
update-localeon Debian and Ubuntu. Debian 13 does not letlocalectlchange the system locale, not even as root: Debian keeps it in/etc/default/locale, whichupdate-localefrom thelocalespackage writes. Debian 13's restriction onlocalectlis why MMX usesupdate-localeon every Debian and Ubuntu node.
This page is docs/reference/modules/locale.md in the MMX repository.