Check and Prepare a Linux Locale with validlocale

validlocale answers one narrow but useful question: can this machine use a named locale right now. If it cannot, the command also prints the line to add to /etc/locale.gen before running locale-gen.

Allow about five minutes for a check, and longer if you need to edit the system locale configuration and generate locale data. This guide describes the locales package version 2.39-0ubuntu8.9 installed on the reference Ubuntu system.

1. Check the installed command

Run the check as your normal user. It reads locale data and does not change the system:

$ command -v validlocale
/usr/sbin/validlocale
$ validlocale C
locale 'C' valid and available

The success message is written to standard error, which is easy to miss if you only capture standard output. The exit status is the reliable, script-friendly result:

$ validlocale C >/dev/null
$ printf 'exit status: %s\n' "$?"
exit status: 0

Checkpoint: Status 0 means the requested locale is valid and available to the process. It does not mean that every locale on the system has been generated.

2. Check the locale your program needs

Pass one locale name as the only argument. Use the spelling expected by the application, including its character set or modifier when those are part of the name:

$ validlocale en_US.utf8
locale 'en_US.utf8' valid and available

Names are not interchangeable merely because they look similar. On the reference machine, en_GB.UTF-8 is listed as supported but has not been generated, so it is not available to setlocale:

$ validlocale en_GB.UTF-8
locale 'en_GB.UTF-8' not available
en_GB.UTF-8 UTF-8
$ printf 'exit status: %s\n' "$?"
exit status: 1

Your generated set will differ. Confirm it independently with locale -a, which lists the locale names currently installed, while /usr/share/i18n/SUPPORTED describes names the distribution knows how to generate.

3. Read the suggested locale.gen entry

When a locale is unavailable, validlocale writes two useful pieces of information. The diagnostic goes to standard error; the line on standard output is the candidate entry for /etc/locale.gen:

$ validlocale de_AU@euro
locale 'de_AU@euro' not available
de_AU@euro ISO-8859-1

The final line is output, not an instruction for your shell to execute: inspect it before changing anything. For an unknown locale, this installed version falls back to ISO-8859-1 unless you set DEFAULTCHARSET, and that fallback is a guess about the character set, not proof the locale exists upstream.

If your input already includes a character set, the command preserves it in the suggested locale name. If not, it looks for a matching entry in /usr/share/i18n/SUPPORTED and otherwise falls back to DEFAULTCHARSET, whose default in this script is ISO-8859-1.

4. Enable and generate a supported locale

Warning: Editing /etc/locale.gen and generating locale data require elevated privileges. Do not do this just to make an arbitrary spelling pass validation. First establish that the exact locale appears in /usr/share/i18n/SUPPORTED:

$ grep -F 'en_GB.UTF-8 ' /usr/share/i18n/SUPPORTED
en_GB.UTF-8 UTF-8

Open the configuration with a root-aware editor and add the exact line printed by validlocale:

$ sudoedit /etc/locale.gen

Keep the change small. Do not remove unrelated entries, and do not replace the file with output from an unreviewed command. After saving, generate the enabled entries:

$ sudo locale-gen
Generating locales (this might take a while)...
  en_GB.UTF-8... done
Generation complete.

Output varies by distribution and by the entries enabled. Re-run the check rather than relying on the generator's progress text:

$ validlocale en_GB.UTF-8
locale 'en_GB.UTF-8' valid and available
$ locale -a | grep -F 'en_GB'
en_GB.utf8

Recovery: Undo is straightforward if the new locale is not wanted: remove or comment out the line you added in /etc/locale.gen. Existing generated data may remain until the next distribution-specific purge or regeneration, so check your package documentation before trying to remove compiled locale data. This guide does not use the destructive locale-gen --purge option.

5. Handle common failures

Calling the command without an argument prints usage and exits 1:

$ validlocale
Usage: /usr/sbin/validlocale <locale>

• Non-zero for a plausible-looking name usually means one of two things. Either the locale is supported but not generated, or the name does not exist in the distribution's supported list.
• Compare three sources before editing configuration. validlocale, locale -a, and /usr/share/i18n/SUPPORTED each tell you something different.
• Do not confuse a suggested entry with a successful check. The command exits 1 until the locale has actually been generated.
• Do not use sudo for the read-only checks. Privileges cannot invent a missing locale definition.

Done means

• Exact locale checked. You checked the exact locale name required by the application.
• Exit status used. You relied on the exit status, not only the diagnostic stream, to decide availability.
• Generated versus supported distinguished. You told generated locales apart from entries merely supported by the distribution.
• Suggested entry reviewed. You checked any suggested /etc/locale.gen line before using elevated privileges.
• Generation scoped. locale-gen ran only for a supported, intentionally enabled locale.
• Final check passed. A final validlocale check returns status 0.