23.2. Using Localization

Localization settings are based on three components: the language code, country code, and encoding. Locale names are constructed from these parts as follows:

LanguageCode_CountryCode.Encoding

The LanguageCode and CountryCode are used to determine the country and the specific language variation. Table 23.1, “Common Language and Country Codes” provides some examples of LanguageCode_CountryCode:

Table 23.1. Common Language and Country Codes
LanguageCode_Country CodeDescription
en_USEnglish, United States
ru_RURussian, Russia
zh_TWTraditional Chinese, Taiwan

A complete listing of available locales can be found by typing:

% locale -a | more

To determine the current locale setting:

% locale

Language specific character sets, such as ISO8859-1, ISO8859-15, KOI8-R, and CP437, are described in multibyte(3). The active list of character sets can be found at the IANA Registry.

Some languages, such as Chinese or Japanese, cannot be represented using ASCII characters and require an extended language encoding using either wide or multibyte characters. Examples of wide or multibyte encodings include EUC and Big5. Older applications may mistake these encodings for control characters while newer applications usually recognize these characters. Depending on the implementation, users may be required to compile an application with wide or multibyte character support, or to configure it correctly.

Note:

FreeBSD uses Xorg-compatible locale encodings.

The rest of this section describes the various methods for configuring the locale on a FreeBSD system. The next section will discuss the considerations for finding and compiling applications with i18n support.

23.2.1. Setting Locale for Login Shell

Locale settings are configured either in a user's ~/.login_conf or in the startup file of the user's shell: ~/.profile, ~/.bashrc, or ~/.cshrc.

Two environment variables should be set:

  • LANG, which sets the locale

  • MM_CHARSET, which sets the MIME character set used by applications

In addition to the user's shell configuration, these variables should also be set for specific application configuration and Xorg configuration.

Two methods are available for making the needed variable assignments: the login class method, which is the recommended method, and the startup file method. The next two sections demonstrate how to use both methods.

23.2.1.1. Login Classes Method

This first method is the recommended method as it assigns the required environment variables for locale name and MIME character sets for every possible shell. This setup can either be performed by each user or it can be configured for all users by the superuser.

This minimal example sets both variables for Latin-1 encoding in the .login_conf of an individual user's home directory:

me:\
	:charset=ISO-8859-1:\
	:lang=de_DE.ISO8859-1:

Here is an example of a user's ~/.login_conf that sets the variables for Traditional Chinese in BIG-5 encoding. More variables are needed because some applications do not correctly respect locale variables for Chinese, Japanese, and Korean:

#Users who do not wish to use monetary units or time formats
#of Taiwan can manually change each variable
me:\
	:lang=zh_TW.Big5:\
	:setenv=LC_ALL=zh_TW.Big5,LC_COLLATE=zh_TW.Big5,LC_CTYPE=zh_TW.Big5,LC_MESSAGES=zh_TW.Big5,LC_MONETARY=zh_TW.Big5,LC_NUMERIC=zh_TW.Big5,LC_TIME=zh_TW.Big5:\
	:charset=big5:\
	:xmodifiers="@im=gcin": #Set gcin as the XIM Input Server

Alternately, the superuser can configure all users of the system for localization. The following variables in /etc/login.conf are used to set the locale and MIME character set:

language_name|Account Type Description:\
	:charset=MIME_charset:\
	:lang=locale_name:\
	:tc=default:

So, the previous Latin-1 example would look like this:

german|German Users Accounts:\
	:charset=ISO-8859-1:\
	:lang=de_DE.ISO8859-1:\
	:tc=default:

See login.conf(5) for more details about these variables. Note that it already contains pre-defined russian class.

Whenever /etc/login.conf is edited, remember to execute the following command to update the capability database:

# cap_mkdb /etc/login.conf

Note:

For an end user, the cap_mkdb command will need to be run on their ~/.login_conf for any changes to take effect.

23.2.1.1.1. Utilities Which Change Login Classes

In addition to manually editing /etc/login.conf, several utilities are available for setting the locale for newly created users.

When using vipw to add new users, specify the language to set the locale:

user:password:1111:11:language:0:0:User Name:/home/user:/bin/sh

When using adduser to add new users, the default language can be pre-configured for all new users or specified for an individual user.

If all new users use the same language, set defaultclass=language in /etc/adduser.conf.

To override this setting when creating a user, either input the required locale at this prompt:

Enter login class: default []:

or specify the locale to set when invoking adduser:

# adduser -class language

If pw is used to add new users, specify the locale as follows:

# pw useradd user_name -L language

To change the login class of an existing user, chpass can be used. Invoke it as superuser and provide the username to edit as the argument.

# chpass user_name

23.2.1.2. Shell Startup File Method

This second method is not recommended as each shell that is used requires manual configuration, where each shell has a different configuration file and differing syntax. As an example, to set the German language for the sh shell, these lines could be added to ~/.profile to set the shell for that user only. These lines could also be added to /etc/profile or /usr/share/skel/dot.profile to set that shell for all users:

LANG=de_DE.ISO8859-1; export LANG
MM_CHARSET=ISO-8859-1; export MM_CHARSET

However, the name of the configuration file and the syntax used differs for the csh shell. These are the equivalent settings for ~/.csh.login, /etc/csh.login, or /usr/share/skel/dot.login:

setenv LANG de_DE.ISO8859-1
setenv MM_CHARSET ISO-8859-1

To complicate matters, the syntax needed to configure Xorg in ~/.xinitrc also depends upon the shell. The first example is for the sh shell and the second is for the csh shell:

LANG=de_DE.ISO8859-1; export LANG
setenv LANG de_DE.ISO8859-1

23.2.2. Console Setup

Several localized fonts are available for the console. To see a listing of available fonts, type ls /usr/share/syscons/fonts. To configure the console font, specify the font_name, without the .fnt suffix, in /etc/rc.conf:

font8x16=font_name
font8x14=font_name
font8x8=font_name

The keymap and screenmap can be set by adding the following to /etc/rc.conf:

scrnmap=screenmap_name
keymap=keymap_name
keychange="fkey_number sequence"

To see the list of available screenmaps, type ls /usr/share/syscons/scrnmaps. Do not include the .scm suffix when specifying screenmap_name. A screenmap with a corresponding mapped font is usually needed as a workaround for expanding bit 8 to bit 9 on a VGA adapter's font character matrix so that letters are moved out of the pseudographics area if the screen font uses a bit 8 column.

To see the list of available keymaps, type ls /usr/share/syscons/keymaps. When specifying the keymap_name, do not include the .kbd suffix. To test keymaps without rebooting, use kbdmap(1).

The keychange entry is usually needed to program function keys to match the selected terminal type because function key sequences cannot be defined in the keymap.

Next, set the correct console terminal type in /etc/ttys for all virtual terminal entries. Table 23.2, “Defined Terminal Types for Character Sets” summarizes the available terminal types.:

Table 23.2. Defined Terminal Types for Character Sets
Character SetTerminal Type
ISO8859-1 or ISO8859-15cons25l1
ISO8859-2cons25l2
ISO8859-7cons25l7
KOI8-Rcons25r
KOI8-Ucons25u
CP437 (VGA default)cons25
US-ASCIIcons25w

For languages with wide or multibyte characters, install a console for that language from the FreeBSD Ports Collection. The available ports are summarized in Table 23.3, “Available Console from Ports Collection”. Once installed, refer to the port's pkg-message or man pages for configuration and usage instructions.

Table 23.3. Available Console from Ports Collection
LanguagePort Location
Traditional Chinese (BIG-5)chinese/big5con
Chinese/Japanese/Koreanchinese/cce
Chinese/Japanese/Koreanchinese/zhcon
Japanesechinese/kon2
Japanesejapanese/kon2-14dot
Japanesejapanese/kon2-16dot

If moused is enabled in /etc/rc.conf, additional configuration may be required. By default, the mouse cursor of the syscons(4) driver occupies the 0xd0-0xd3 range in the character set. If the language uses this range, move the cursor's range by adding the following line to /etc/rc.conf:

mousechar_start=3

23.2.3. Xorg Setup

Chapter 5, The X Window System describes how to install and configure Xorg. When configuring Xorg for localization, additional fonts and input methods are available from the FreeBSD Ports Collection. Application specific i18n settings such as fonts and menus can be tuned in ~/.Xresources and should allow users to view their selected language in graphical application menus.

The X Input Method (XIM) protocol is an Xorg standard for inputting non-English characters. Table 23.4, “Available Input Methods” summarizes the input method applications which are available in the FreeBSD Ports Collection. Additional Fcitx and Uim applications are also available.


All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.