source: chapter09/locale.xml@ 6ebb3b9

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../general.ent">
  %general-entities;
]>

<sect1 id="ch-config-locale">
  <?dbhtml filename="locale.html"?>

  <title>Configuring the System Locale</title>

  <indexterm zone="ch-config-locale">
    <primary sortas="e-/etc/profile">/etc/profile</primary>
  </indexterm>

  <indexterm zone="ch-config-locale" revision='systemd'>
    <primary sortas="e-/etc/profile">/etc/locale.conf</primary>
  </indexterm>

  <para revision='systemd'>The <filename>/etc/locale.conf</filename> file
  below sets some environment variables necessary for native language
  support. Setting them properly results in:</para>

  <para>Some environment variables are necessary for native language
  support. Setting them properly results in:</para>

  <itemizedlist>
    <listitem>
      <para>The output of programs being translated into your native language</para>
    </listitem>
    <listitem>
      <para>The correct classification of characters into letters, digits and other
      classes. This is necessary for <command>bash</command> to properly accept
      non-ASCII characters in command lines in non-English locales</para>
    </listitem>
    <listitem>
      <para>The correct alphabetical sorting order for the country</para>
    </listitem>
    <listitem>
      <para>The appropriate default paper size</para>
    </listitem>
    <listitem>
      <para>The correct formatting of monetary, time, and date values</para>
    </listitem>
  </itemizedlist>

  <para>Replace <replaceable>&lt;ll&gt;</replaceable> below with the two-letter code
  for your desired language (e.g., <literal>en</literal>) and
  <replaceable>&lt;CC&gt;</replaceable> with the two-letter code for the appropriate
  country (e.g., <literal>GB</literal>). <replaceable>&lt;charmap&gt;</replaceable> should
  be replaced with the canonical charmap for your chosen locale. Optional
  modifiers such as <literal>@euro</literal> may also be present.</para>

  <para>The list of all locales supported by Glibc can be obtained by running
  the following command:</para>

<screen role="nodump"><userinput>locale -a</userinput></screen>

  <para>Charmaps can have a number of aliases, e.g.,
  <literal>ISO-8859-1</literal> is also referred to as
  <literal>iso8859-1</literal> and <literal>iso88591</literal>.
  Some applications cannot handle the various synonyms correctly (e.g., require
  that <literal>UTF-8</literal> is written as <literal>UTF-8</literal>, not
  <literal>utf8</literal>), so it is the safest in most
  cases to choose the canonical name for a particular locale. To determine
  the canonical name, run the following command, where <replaceable>&lt;locale
  name&gt;</replaceable> is the output given by <command>locale -a</command> for
  your preferred locale (<literal>en_GB.iso88591</literal> in our
  example).</para>

<screen role="nodump"><userinput>LC_ALL=<replaceable>&lt;locale name&gt;</replaceable> locale charmap</userinput></screen>

  <para>For the <literal>en_GB.iso88591</literal> locale, the above command
  will print:</para>

<screen><computeroutput>ISO-8859-1</computeroutput></screen>

  <para>This results in a final locale setting of <literal>en_GB.ISO-8859-1</literal>.
  It is important that the locale found using the heuristic above is tested prior
  to it being added to the Bash startup files:</para>

<screen role="nodump"><userinput>LC_ALL=&lt;locale name&gt; locale language
LC_ALL=&lt;locale name&gt; locale charmap
LC_ALL=&lt;locale name&gt; locale int_curr_symbol
LC_ALL=&lt;locale name&gt; locale int_prefix</userinput></screen>

  <para>The above commands should print the language name, the character
  encoding used by the locale, the local currency, and the prefix to dial
  before the telephone number in order to get into the country. If any of the
  commands above fail with a message similar to the one shown below, this means
  that your locale was either not installed in Chapter&nbsp;8 or is not
  supported by the default installation of Glibc.</para>

<screen><computeroutput>locale: Cannot set LC_* to default locale: No such file or directory</computeroutput></screen>

  <para>If this happens, you should either install the desired locale using the
  <command>localedef</command> command, or consider choosing a different locale.
  Further instructions assume that there are no such error messages from
  Glibc.</para>

  <para>Other packages can also function incorrectly (but may not necessarily
  display any error messages) if the locale name does not meet their expectations.
  In those cases, investigating how other Linux distributions support your locale
  might provide some useful information.</para>

  <para revision='systemd'>Once the proper locale settings have been
  determined, create the <filename>/etc/locale.conf</filename> file:</para>

<screen revision='systemd'><userinput>cat &gt; /etc/locale.conf &lt;&lt; "EOF"
<literal>LANG=<replaceable>&lt;ll&gt;_&lt;CC&gt;.&lt;charmap&gt;&lt;@modifiers&gt;</replaceable></literal>
EOF</userinput></screen>

  <para>The shell program <command>/bin/bash</command> (here after referred
  as <quote>the shell</quote>) uses a collection of startup files to help
  create the environment to run in. Each file has a specific use and may
  affect login and interactive environments differently. The files in the
  <filename class="directory">/etc</filename> directory provide global
  settings.  If equivalent files exist in the home directory, they
  may override the global settings.</para>

  <para>An interactive login shell is started after a successful login,
  using <command>/bin/login</command>, by reading the
  <filename>/etc/passwd</filename> file.  An interactive non-login shell is
  started at the command-line (e.g.
  <prompt>[prompt]$</prompt><command>/bin/bash</command>).  A
  non-interactive shell is usually present when a shell script is running.
  It is non-interactive because it is processing a script and not waiting
  for user input between commands.</para>

  <para><phrase revision='systemd'>The login shells are often unaffected by
  the settings in <filename>/etc/locale.conf</filename>. </phrase>Create the
  <filename>/etc/profile</filename>
  <phrase revision='sysv'>once the proper locale settings have been
  determined to set the desired locale</phrase><phrase
  revision='systemd'>to read the locale settings from
  <filename>/etc/locale.conf</filename> and export them</phrase>,
  but set the <literal>C</literal> locale instead if running in the Linux
  console (to prevent programs from outputting characters that the Linux
  console is unable to render):</para>

<screen revision="systemd"><userinput>cat &gt; /etc/profile &lt;&lt; "EOF"
<literal># Begin /etc/profile

for i in $(locale); do
  unset ${i%=*}
done

if [[ "$TERM" = linux ]]; then
  export LANG=C
else
  source /etc/locale.conf

  for i in $(locale); do
    key=${i%=*}
    if [[ -v $key ]]; then
      export $key
    fi
  done
fi

# End /etc/profile</literal>
EOF</userinput></screen>

<screen revision="sysv"><userinput>cat &gt; /etc/profile &lt;&lt; "EOF"
<literal># Begin /etc/profile

for i in $(locale); do
  unset ${i%=*}
done

if [[ "$TERM" = linux ]]; then
  for i in $(locale); do
    unset ${i%=*}
  done

  export LANG=C
else
  export LANG=<replaceable>&lt;ll&gt;_&lt;CC&gt;.&lt;charmap&gt;&lt;@modifiers&gt;</replaceable>
fi

# End /etc/profile</literal>
EOF</userinput></screen>

  <para revision='systemd'>Note that you can modify <filename>/etc/locale.conf</filename> with the
  systemd <command>localectl</command> utility. To use
  <command>localectl</command> for the example above, run:</para>

<screen revision='systemd' role="nodump"><userinput>localectl set-locale LANG="<replaceable>&lt;ll&gt;_&lt;CC&gt;.&lt;charmap&gt;&lt;@modifiers&gt;</replaceable>"</userinput></screen>

  <para revision='systemd'>You can also specify other language specific
  environment variables such as <envar>LANG</envar>,
  <envar>LC_CTYPE</envar>, <envar>LC_NUMERIC</envar> or any other
  environment variable from <command>locale</command> output. Just separate
  them with a space. An example where <envar>LANG</envar> is set as
  en_US.UTF-8 but <envar>LC_CTYPE</envar> is set as just en_US is:</para>

<screen revision='systemd' role="nodump"><userinput>localectl set-locale LANG="en_US.UTF-8" LC_CTYPE="en_US"</userinput></screen>

  <note revision='systemd'><para>Please note that the
  <command>localectl</command> command doesn't work in the chroot
  environment.  It can only be used after the LFS system is booted with
  systemd.</para></note>

  <para>The <literal>C</literal> (default) and <literal>en_US</literal>
  (the recommended one for United States English users) locales are
  different. <literal>C</literal>
  uses the US-ASCII 7-bit character set, and treats bytes with the high bit set
  as invalid characters. That's why, e.g., the <command>ls</command> command
  substitutes them with question marks in that locale. Also, an attempt to send
  mail with such characters from Mutt or Pine results in non-RFC-conforming
  messages being sent (the charset in the outgoing mail is indicated as
  <computeroutput>unknown 8-bit</computeroutput>). It's suggested that you
  use the <literal>C</literal> locale only
  if you are certain that you will never need 8-bit characters.</para>

</sect1>