Request adding documentation on how to configure the system/user locale

[brlin-tw]

I was looking for information on solving the following Ansible task error, to be specific:

TASK [ossii.init : Configure preferred UI localization settings(Systemd-based distros)] ***********
fatal: [host]: FAILED! => 
    changed: false
    cmd:
    - localectl
    - set-locale
    - LANGUAGE=zh_TW:zh:en
    delta: '0:00:00.008622'
    end: '2025-09-19 09:46:24.236281'
    failed_when_result: true
    msg: non-zero return code
    rc: 1
    start: '2025-09-19 09:46:24.227659'
    stderr: 'Failed to issue method call: Locale zh_TW:zh:en not installed, refusing.'
    stderr_lines: <omitted>
    stdout: ''
    stdout_lines: <omitted>

[sspencerwire]

Hi @brlin-tw I do not know if any of this will answer your question, but have you checked out this resource: https://docs.rockylinux.org/books/learning_ansible/00-toc/ If that is of no help, I can ask @alemorvan who has worked quite a bit with ansible if he knows the answer.

[NezSez]

Note that 'man localectl' states that the initrd is not rebuilt by using it, and must be done manually, but is only needed if the locale is required in the early boot stages apparently.
'locale' will list the current settings
'locale -a' will list all the installed locales
As the error indicates, "Locale zh_TW:zh:en not installed" because it doesn't match anything in the locale database.
For the ansible 'cmd' maybe the "LANGUAGE=" should be just "zh_TW" or "zh_TW.utf8"?

[alemorvan]

Maybe using something like that:

- name: Configure LANGUAGE in /etc/locale.conf
  ansible.builtin.lineinfile:
    path: /etc/locale.conf
    regexp: '^LANGUAGE='
    line: 'LANGUAGE=zh_TW'
    create: yes
  become: true

Try not to use cmd when possible.

[brlin-tw]

Hello, and apologies for the ignorance!

This is my solution:

- name: Ensure that the Chinese locale data is installed
  when: ansible_os_family == "RedHat"
  become: true
  ansible.builtin.package:
    name:
      - glibc-langpack-zh

- name: Configure the preferred UI localization settings
  when: ansible_os_family == "RedHat"
  become: true
  ansible.builtin.lineinfile:
    path: /etc/locale.conf
    regexp: '^LANGUAGE='
    line: 'LANGUAGE="zh_TW:zh:en"'

[brlin-tw]

@NezSez

For the ansible 'cmd' maybe the "LANGUAGE=" should be just "zh_TW" or "zh_TW.utf8"?

The LANGUAGE environment variable is supposed to support holding a locale string list separated by the colon character, which represents the preferred order of showing localization strings.

Refer to User influence on gettext - The GNU C Library - Message Translation for more information:

The locale component is computed based on the category used. Just like for the
setlocale function here comes the user selection into the play. Some environment variables are examined in a fixed order and the first environment variable set determines the return value of the lookup process. In detail, for the category LC_xxx the following variables in this order are examined:

LANGUAGE

LC_ALL

LC_xxx

LANG

This looks very familiar. With the exception of the LANGUAGE environment variable this is exactly the lookup order the setlocale function uses. But why introducing the LANGUAGE variable?

The reason is that the syntax of the values these variables can have is different to what is expected by the setlocale function. If we would set LC_ALL to a value following the extended syntax that would mean the setlocale function will never be able to use the value of this variable as well. An additional variable removes this problem plus we can select the language independently of the locale setting which sometimes is useful.

While for the LC_xxx variables the value should consist of exactly one specification of a locale the LANGUAGE variable's value can consist of a colon separated list of locale names. The attentive reader will realize that this is the way we manage to implement one of our additional demands above: we want to be able to specify an ordered list of language.