---
title: Chapter 25. Localization - i18n/L10n Usage and Setup
part: Part III. System Administration
prev: books/handbook/virtualization
next: books/handbook/cutting-edge
description: FreeBSD supports localization into many languages, allowing users to view, input, or process data in non-English languages
tags: ["i18n", "L10n", "localization", "Locale", "LANG", "MM_CHARSET", "cap_mkdb"]
showBookMenu: true
weight: 29
params:
  path: "/books/handbook/l10n/"
---

[[l10n]]
= Localization - i18n/L10n Usage and Setup
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:sectnumoffset: 25
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/handbook/l10n/

ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]

ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]

[[l10n-synopsis]]
== Synopsis

FreeBSD is a distributed project with users and contributors located all over the world.
As such, FreeBSD supports localization into many languages, allowing users to view, input, or process data in non-English languages.
One can choose from most of the major languages, including, but not limited to: Chinese, German, Japanese, Korean, French, Russian, and Vietnamese.

The term internationalization has been shortened to i18n, which represents the number of letters between the first and the last letters of `internationalization`.
L10n uses the same naming scheme, but from `localization`.
The i18n/L10n methods, protocols, and applications allow users to use languages of their choice.

This chapter discusses the internationalization and localization features of FreeBSD.

Read this chapter to learn:

* How locale names are constructed.
* How to set the locale for a login shell.
* How to configure the console for non-English languages.
* How to configure Xorg for different languages.
* How to find i18n-compliant applications.
* Where to find more information for configuring specific languages.

Before reading this chapter:

* Know how to crossref:ports[ports,install additional third-party applications].

[[using-localization]]
== 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:

[.programlisting]
....
LanguageCode_CountryCode.Encoding
....

The _LanguageCode_ and _CountryCode_ are used to determine the country and the specific language variation.
crossref:l10n[locale-lang-country,Common Language and Country Codes] provides some examples of __LanguageCode_CountryCode__:

[[locale-lang-country]]
.Common Language and Country Codes
[cols="1,1", frame="none", options="header"]
|===
| LanguageCode_Country Code
| Description

|en_US
|English, United States

|ru_RU
|Russian, Russia

|zh_TW
|Traditional Chinese, Taiwan
|===

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

[source,shell]
....
% locale -a | more
....

To determine the current locale setting:

[source,shell]
....
% locale
....

Language specific character sets, such as ISO8859-1, ISO8859-15, KOI8-R, and CP437, are described in man:multibyte[3].
The active list of character sets can be found at the http://www.iana.org/assignments/character-sets[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.

[[setting-locale]]
=== Setting Locale for Login Shell

Locale settings are configured either in a user's [.filename]#~/.login_conf# or in the startup file of the user's shell: [.filename]#~/.profile#, [.filename]#~/.bashrc#, or [.filename]#~/.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
crossref:l10n[login-class,login class] method, which is the recommended method,
and the crossref:l10n[startup-file,startup file] method.
The next two sections demonstrate how to use both methods.

[[login-class]]
==== 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 [.filename]#.login_conf# of an individual user's home directory:

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

Here is an example of a user's [.filename]#~/.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:

[.programlisting]
....
#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 [.filename]#/etc/login.conf# are used to set the locale and MIME character set:

[.programlisting]
....
language_name|Account Type Description:\
	:charset=MIME_charset:\
	:lang=locale_name:\
	:tc=default:
....

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

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

See man:login.conf[5] for more details about these variables.
Note that it already contains pre-defined _russian_ class.

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

[source,shell]
....
# cap_mkdb /etc/login.conf
....

[NOTE]
====
For an end user, the `cap_mkdb` command will need to be run on their [.filename]#~/.login_conf# for any changes to take effect.
====

===== Utilities Which Change Login Classes

In addition to manually editing [.filename]#/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:

[.programlisting]
....
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 [.filename]#/etc/adduser.conf#.

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

[source,shell]
....
Enter login class: default []:
....

or specify the locale to set when invoking `adduser`:

[source,shell]
....
# adduser -class language
....

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

[source,shell]
....
# 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.

[source,shell]
....
# chpass user_name
....


[[startup-file]]
==== 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 [.filename]#~/.profile# to set the shell for that user only.
These lines could also be added to [.filename]#/etc/profile# or [.filename]#/usr/share/skel/dot.profile# to set that shell for all users:

[.programlisting]
....
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 [.filename]#~/.login#, [.filename]#/etc/csh.login#, or [.filename]#/usr/share/skel/dot.login#:

[.programlisting]
....
setenv LANG de_DE.ISO8859-1
setenv MM_CHARSET ISO-8859-1
....

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

[.programlisting]
....
LANG=de_DE.ISO8859-1; export LANG
....


[.programlisting]
....
setenv LANG de_DE.ISO8859-1
....


[[setting-console]]
=== 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 [.filename]#.fnt# suffix, in [.filename]#/etc/rc.conf#:

[.programlisting]
....
font8x16=font_name
font8x14=font_name
font8x8=font_name
....

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

[.programlisting]
....
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 [.filename]#.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 [.filename]#.kbd# suffix.
To test keymaps without rebooting, use man: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 [.filename]#/etc/ttys# for all virtual terminal entries.
crossref:l10n[locale-charset,Defined Terminal Types for Character Sets] summarizes the available terminal types.:

[[locale-charset]]
.Defined Terminal Types for Character Sets
[cols="1,1", frame="none", options="header"]
|===
| Character Set
| Terminal Type

|ISO8859-1 or ISO8859-15
|`cons25l1`

|ISO8859-2
|`cons25l2`

|ISO8859-7
|`cons25l7`

|KOI8-R
|`cons25r`

|KOI8-U
|`cons25u`

|CP437 (VGA default)
|`cons25`

|US-ASCII
|`cons25w`
|===

For languages with wide or multibyte characters, install a console for that language from the FreeBSD Ports Collection.
The available ports are summarized in crossref:l10n[locale-console,Available Console from Ports Collection].
Once installed, refer to the port's [.filename]#pkg-message# or man pages for configuration and usage instructions.

[[locale-console]]
.Available Console from Ports Collection
[cols="1,1", frame="none", options="header"]
|===
| Language
| Port Location

|Traditional Chinese (BIG-5)
|package:chinese/big5con[]

|Chinese/Japanese/Korean
|package:chinese/cce[]

|Chinese/Japanese/Korean
|package:chinese/zhcon[]

|Japanese
|package:chinese/kon2[]

|Japanese
|package:japanese/kon2-14dot[]

|Japanese
|package:japanese/kon2-16dot[]
|===

If moused is enabled in [.filename]#/etc/rc.conf#, additional configuration may be required.
By default, the mouse cursor of the man: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 [.filename]#/etc/rc.conf#:

[.programlisting]
....
mousechar_start=3
....

=== Xorg Setup

crossref:x11[x11,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 [.filename]#~/.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.
crossref:l10n[locale-xim,Available Input Methods] summarizes the input method applications which are available in the FreeBSD Ports Collection.
Additional Fcitx and Uim applications are also available.

[[locale-xim]]
.Available Input Methods
[cols="1,1", frame="none", options="header"]
|===
| Language
| Input Method

|Chinese
|package:chinese/gcin[]

|Chinese
|package:chinese/ibus-chewing[]

|Chinese
|package:chinese/ibus-pinyin[]

|Chinese
|package:chinese/oxim[]

|Chinese
|package:chinese/scim-fcitx[]

|Chinese
|package:chinese/scim-pinyin[]

|Chinese
|package:chinese/scim-tables[]

|Japanese
|package:japanese/ibus-anthy[]

|Japanese
|package:japanese/ibus-mozc[]

|Japanese
|package:japanese/ibus-skk[]

|Japanese
|package:japanese/im-ja[]

|Japanese
|package:japanese/kinput2[]

|Japanese
|package:japanese/scim-anthy[]

|Japanese
|package:japanese/scim-canna[]

|Japanese
|package:japanese/scim-honoka[]

|Japanese
|package:japanese/scim-honoka-plugin-romkan[]

|Japanese
|package:japanese/scim-honoka-plugin-wnn[]

|Japanese
|package:japanese/scim-prime[]

|Japanese
|package:japanese/scim-skk[]

|Japanese
|package:japanese/scim-tables[]

|Japanese
|package:japanese/scim-tomoe[]

|Japanese
|package:japanese/scim-uim[]

|Japanese
|package:japanese/skkinput[]

|Japanese
|package:japanese/skkinput3[]

|Japanese
|package:japanese/uim-anthy[]

|Korean
|package:korean/ibus-hangul[]

|Korean
|package:korean/imhangul[]

|Korean
|package:korean/nabi[]

|Korean
|package:korean/scim-hangul[]

|Korean
|package:korean/scim-tables[]

|Vietnamese
|package:vietnamese/xvnkb[]

|Vietnamese
|package:vietnamese/x-unikey[]
|===

[[l10n-compiling]]
== Finding i18n Applications

i18n applications are programmed using i18n kits under libraries.
These allow developers to write a simple file and translate displayed menus and texts to each language.

The link:https://ports.FreeBSD.org[FreeBSD Ports Collection] contains many applications with built-in support for wide or multibyte characters for several languages.
Such applications include `i18n` in their names for easy identification.
However, they do not always support the language needed.

Some applications can be compiled with the specific charset.
This is usually done in the port's [.filename]#Makefile# or by passing a value to configure.
Refer to the i18n documentation in the respective FreeBSD port's source for more information on how to determine the needed configure value or the port's [.filename]#Makefile# to determine which compile options to use when building the port.

[[lang-setup]]
== Locale Configuration for Specific Languages

This section provides configuration examples for localizing a FreeBSD system for the Russian language.
It then provides some additional resources for localizing other languages.

[[ru-localize]]
=== Russian Language (KOI8-R Encoding)

This section shows the specific settings needed to localize a FreeBSD system for the Russian language.
Refer to crossref:l10n[using-localization,Using Localization] for a complete description of each type of setting.

To set this locale for the login shell, add the following lines to each user's [.filename]#~/.login_conf#:

[.programlisting]
....
me:My Account:\
	:charset=KOI8-R:\
	:lang=ru_RU.KOI8-R:
....

To configure the console, add the following lines to [.filename]#/etc/rc.conf#:

[.programlisting]
....
keymap="ru.utf-8"
scrnmap="utf-82cp866"
font8x16="cp866b-8x16"
font8x14="cp866-8x14"
font8x8="cp866-8x8"
mousechar_start=3
....

For each `ttyv` entry in [.filename]#/etc/ttys#, use `cons25r` as the terminal type.

To configure printing, a special output filter is needed to convert from KOI8-R to CP866 since most printers with Russian characters come with hardware code page CP866.
FreeBSD includes a default filter for this purpose, [.filename]#/usr/libexec/lpr/ru/koi2alt#.
To use this filter, add this entry to [.filename]#/etc/printcap#:

[.programlisting]
....
lp|Russian local line printer:\
	:sh:of=/usr/libexec/lpr/ru/koi2alt:\
	:lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:
....

Refer to man:printcap[5] for a more detailed explanation.

To configure support for Russian filenames in mounted MS-DOS(R) file systems, include `-L` and the locale name when adding an entry to [.filename]#/etc/fstab#:

[.programlisting]
....
/dev/ad0s2      /dos/c  msdos   rw,-Lru_RU.KOI8-R 0 0
....

Refer to man:mount_msdosfs[8] for more details.

To configure Russian fonts for Xorg, install the package:x11-fonts/xorg-fonts-cyrillic[] package.
Then, check the `"Files"` section in [.filename]#/etc/X11/xorg.conf#. The following line must be added _before_ any other `FontPath` entries:

[.programlisting]
....
FontPath   "/usr/local/lib/X11/fonts/cyrillic"
....

Additional Cyrillic fonts are available in the Ports Collection.

To activate a Russian keyboard, add the following to the `"Keyboard"` section of [.filename]#/etc/xorg.conf#:

[.programlisting]
....
Option "XkbLayout"   "us,ru"
Option "XkbOptions"  "grp:toggle"
....

Make sure that `XkbDisable` is commented out in that file.

For `grp:toggle` use kbd:[Right Alt], for `grp:ctrl_shift_toggle` use kbd:[Ctrl+Shift].
For `grp:caps_toggle` use kbd:[CapsLock]. The old kbd:[CapsLock] function is still available in LAT mode only using kbd:[Shift+CapsLock]. `grp:caps_toggle` does not work in Xorg for some unknown reason.

If the keyboard has "Windows(R)" keys, and some non-alphabetical keys are mapped incorrectly, add the following line to [.filename]#/etc/xorg.conf#:

[.programlisting]
....
Option "XkbVariant" ",winkeys"
....

[NOTE]
====
The Russian XKB keyboard may not work with non-localized applications.
Minimally localized applications should call a `XtSetLanguageProc (NULL, NULL, NULL);` function early in the program.
====

See http://koi8.pp.ru/xwin.html[http://koi8.pp.ru/xwin.html] for more instructions on localizing Xorg applications.
For more general information about KOI8-R encoding, refer to http://koi8.pp.ru/[http://koi8.pp.ru/].

=== Additional Language-Specific Resources

This section lists some additional resources for configuring other locales.

Traditional Chinese for Taiwan::
The FreeBSD-Taiwan Project has a Chinese HOWTO for FreeBSD at http://netlab.cse.yzu.edu.tw/\~statue/freebsd/zh-tut/[http://netlab.cse.yzu.edu.tw/~statue/freebsd/zh-tut/].

Greek Language Localization::
A complete article on Greek support in FreeBSD is available https://www.FreeBSD.org/doc/gr/articles/greek-language-support/[here], in Greek only, as part of the official FreeBSD Greek documentation.

Japanese and Korean Language Localization::
For Japanese, refer to http://www.jp.FreeBSD.org/[http://www.jp.FreeBSD.org/], and for Korean, refer to http://www.kr.FreeBSD.org/[http://www.kr.FreeBSD.org/].

Non-English FreeBSD Documentation::
Some FreeBSD contributors have translated parts of the FreeBSD documentation to other languages.
They are available through links on the link:https://www.FreeBSD.org/[FreeBSD web site] or in [.filename]#/usr/share/doc#.
