diff --git a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml index 9d9747f835..2b49829d29 100644 --- a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml @@ -1,735 +1,915 @@ Localization - I18N/L10N Usage and Setup Rewritten by Michael Chin-Yuan Wu keichii@mail.utexas.edu, 6 March 2000. Synopsis This section of the handbook discusses the internationalization and localization of FreeBSD to different countries and different settings. If the users wish to use languages other than the system default English, he/she will have to setup the system accordingly. Please note that language support for each language varies in level. Hence, the user should contact the respective FreeBSD local group that is responsible for each language. The author realizes that he may have been incomplete in the description of the i18n process in FreeBSD. Due to the various levels of i18n implementation in both the system and applicational levels, we advise you to refer to individual documentation, man pages, READMEs, and so forth. Should you have any questions or suggestions regarding this chapter, please email the author. The Basics What is i18n/l10n? Developers shortened internationalization into the term i18n, counting the number of letters between the first and the last letters of internationalization. l10n uses the same naming - scheme, coming from “localization”. Combined + scheme, coming from "localization". Combined together, i18n/l10n methods, protocols, and applications allow users to use languages of their choice. I18n applications are programmed using i18n kits under libraries. It allows for developers to write a simple file and translate displayed menus and texts to each language. We strongly encourage programmers to follow this convention. Why should I use i18n/l10n? I18n/l10n is used whenever you wish to either view, input, or process data in non-English languages. What languages are supported in the i18n effort? I18n and l10n are not FreeBSD specific. Currently, one can choose from most of the major languages of the World, including but not limited to: Chinese, German, Japanese, French, Russian, and others. Using Localization In all its splendor, i18n is not FreeBSD-specific and is a convention. We encourage you to help FreeBSD in following this convention. + Localization settings are based on three main terms: + Language Code, Country Code and Encoding. Locale name constructed + with this three parts as follows: + + +LanguageCode_CountryCode.Encoding + - Language Codes + Language and Country Codes In order to localize a FreeBSD system to a specific language (or any other i18n-supporting UNIX's), the user needs to find out - the language code for the specify country and language. Country - codes tell applications what language to use. In addition, web + the codes for the specify country and language (country + codes tell applications what variation of given + language to use). In addition, web browsers, SMTP/POP servers, HTTPd's, etc. make decisions based on - them. The following are examples of country codes: + them. The following are examples of language/country codes: - Language code + Language/Country Code Description - en - Generic English - - - - en.us - English—United States + en_US + English - United States - ru - Russian + ru_RU + Russian for Russia - zh_TW.Big5 + zh_TW Traditional Chinese for Taiwan - You can read more about character sets and language codes at - ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets. - Encoding + Encodings - Some languages (mostly Asian ones) use non-ASCII encodings - that are 8-bit characters. Older applications do not recognize + Some languages use non-ASCII encodings + that are 8-bit or 16-bit wide characters. + Older applications do not recognize them and mistake them for control characters. Newer applications + usually do recognize 8-bit characters. Depending on implementation, users - may be required to compile the application with 8-bit support - (such as MySQL and Apache), or configure it correctly (such as - telnet, ssh, and system shells). To be able to input and process - 8-bit characters, the FreeBSD Ports + may be required to compile an application with 16-bit support, + or configure it correctly. + To be able to input and process + 16-bit wide characters, the FreeBSD Ports collection has provided each language with different programs. Refer to the i18n documentation in the respective FreeBSD Port. Specifically, the user needs to look at the application documentation to decide on how to configure it correctly or to pass correct values into the configure/Makefile/compiler. Some things to keep in mind are: - UTF-8 encoding + Language specific 8-bit wide character sets, f.e. + ISO_8859-1, KOI8-R, CP437. - Language specific MIME 8-bit support + 16-bit wide encodings, f.e. EUC, Big5. - - Language specific charsets - - - - UUENCODE/UUDECODE - + + You can check active list of character sets at + IANA Registry. - i18n applications + I18n applications In the FreeBSD Ports and Package system, i18n applications have been named with i18n in their names for easy identification. However, they do not always support the language needed. - Non-English users should install i18n libraries and - applications if they wish to use a different locale. Setting Locale Theoretically, one only needs to export the value of his/her - language code as LANG in the login shell and is usually done - through the user login shell configuration - (.profile, .bashrc, or - .cshrc). This should set all of the locale + locale name as LANG + in the login shell and is usually done + through the user's ~/.login_conf or + the user login shell configuration + (~/.profile, ~/.bashrc, + ~/.cshrc). + This should set all of the locale subsets (such as LC_CTYPE, - LC_CTIME, etc.). However, some applications - that do not follow the i18n convention correctly will require you - to set each locale subset specifically. Please refer to + LC_CTIME, etc.). + Please refer to language-specific FreeBSD documentation for more information. You should set the following two values in your configuration files: LANG for POSIX &man.setlocale.3; family functions MM_CHARSET for applications' MIME character set - This includes the user shell config, the specific library + This includes the user shell config, the specific application config, and the X11 config. - Setting Locale - Shell Startup Files Method - - There are two methods for setting locale, and both are - described below. The first is by adding environment variables - to the system's shell startup files, and the second is by login class. To use th first - method, just set the two environment variables shown below in - the /etc/profile and/or - /etc/csh.login shell startup files. We - will use the Russian language as an example below: - - In /etc/profile: - - -LANG=ru_RU.KOI8-R; export LANG -MM_CHARSET=KOI8-R; export MM_CHARSET - - Or in /etc/csh.login: + Setting Locale Methods + + There are two methods for setting locale, and both are + described below. The first (recommended one) is by + setting environment variables assignment in + login class, + and the second is by adding environment variables assignment + to the system's shell + startup file. + + + Login Classes Method + + This method allows to assing environment + variables needed for locale name and MIME character set once + for every possible shell instead of adding specific shell assignment + to each shell startup file. + User Level Setup + can be done by an user himself and + Administrator Level Setup require + superuser priviledges. + + + User Level Setup + + Here is minimal example of ~/.login_conf + file in user's home directory which have both variables set + for Russian KOI8-R encoding: -setenv LANG ru_RU.KOI8-R -setenv MM_CHARSET KOI8-R - - Alternatively, you can add the above instructions to - /usr/share/skel/dot.profile (similar to - what was used in /etc/profile above), or - /usr/share/skel/dot.login (similar to what - was used in /etc/csh.login above). - - For X11: - - In $HOME/.xinitrc: - - -LANG=ru_RU.KOI8-R; export LANG - - Or: - - -setenv LANG ru_RU.KOI8-R +me:My Account:\ + :charset=KOI8-R:\ + :lang=ru_RU.KOI8-R: - Depending on your shell (see above). + See + Administrator Level Setup + and + &man.login.conf.5; for explanation. - In $HOME/.Xresources, you can set - application specific i18n settings (e.g., fonts, display - characters, etc.). - + - - Login Classes - - This method of setting locale should only be used when you - wish each user to be using the language you choose for your - system. If you are a user or wish to allow users to default to - English and change locale themselves, please disregard this - section. + + Administrator Level Setup Check that /etc/login.conf have the correct language user's class. Make sure these settings appear in /etc/login.conf: -language:Title for user accounts:\ - :charset=language charset:\ - :lang=country code.charset:\ +language_name:accounts_title:\ + :charset=MIME_charset:\ + :lang=locale_name:\ :tc=default: So sticking with our previous example using Russian, it would look like this: russian:Russian Users Accounts:\ :charset=KOI8-R:\ :lang=ru_RU.KOI8-R:\ :tc=default: - + Changing Login Classes with &man.vipw.8; Use vipw to add new users, and make the entry look like this: user:password:1111:11:language:0:0:User Name:/home/user:/bin/sh - + - + Changing Login Classes with &man.adduser.8; Use adduser to add new users, and do the following: Set defaultclass = language in /etc/adduser.conf. Keep in mind you must enter default class for all users of other languages in this case. An alternative variant is answering the specified language each time that Enter login class: default []: appears from &man.adduser.8; Another alternative is to use the following for each user of a different language that you wish to add: &prompt.root; adduser -class language - + - + Changing Login Classes with &man.pw.8; If you use &man.pw.8; for adding new users, call it in this form: - &prompt.root; pw useradd user_name -L language - + &prompt.root; pw useradd user_name -L language + + + + + + Shell Startup File Method + + + This method is not recommended because require + different setup for each possible login program choosed. + Use Login Class Method + instead. + + + To add locale name and MIME character set + just set the two environment variables shown below in + the /etc/profile and/or + /etc/csh.login shell startup files. We + will use the Russian language as an example below: + + In /etc/profile: + + +LANG=ru_RU.KOI8-R; export LANG +MM_CHARSET=KOI8-R; export MM_CHARSET + + Or in /etc/csh.login: + + +setenv LANG ru_RU.KOI8-R +setenv MM_CHARSET KOI8-R + + Alternatively, you can add the above instructions to + /usr/share/skel/dot.profile (similar to + what was used in /etc/profile above), or + /usr/share/skel/dot.login (similar to what + was used in /etc/csh.login above). + + For X11: + + In $HOME/.xinitrc: + + +LANG=ru_RU.KOI8-R; export LANG + + Or: + + +setenv LANG ru_RU.KOI8-R + + Depending on your shell (see above). + + + + - - Console + + Console Setup - For all 7-bit Roman languages, set the correct console fonts + For all 8-bit wide languages, set the correct console fonts in /etc/rc.conf for the language in question with: -font8x16=font name -font8x14=font name -font8x8=font name +font8x16=font_name +font8x14=font_name +font8x8=font_name + + font_name here taken from + /usr/share/syscons/fonts directory, + without .fnt suffix. Also be sure to set the correct keymap and screenmap for - your 7-bit language through + your 8-bit language through /stand/sysinstall. Once inside sysinstall, choose Configure, then Console. Alternatively, you can add the following to /etc/rc.conf: -scrnmap=screenmap name -keychange=special key names -keymap=keymap name +scrnmap=screenmap_name +keymap=keymap_name +keychange="fkey_number sequence" + + screenmap_name here taken from + /usr/share/syscons/scrnmaps directory, + without .scm suffix. + Screenmap with corresponding mapped font + is usually needed as workaround for expanding + 8-bit to 9-bit on VGA adapters in pseudographics area, i.e. + to move characters out of that area. + + If you use destructive type of cursor + like following setting in /etc/rc.conf: + + +cursor="destructive" + + (see &man.vidcontrol.1;) + be shure that you compile your kernel with + + +options SC_MOUSE_CHAR=0x03 + + in your kernel configuration file to avoid + 8-bit to 9-bit expansion of mouse cursor image on VGA adapters. + + + keymap_name here taken from + /usr/share/syscons/keymaps directory, + without .kbd suffix. + + keychange is usually needed + to program function keys to match selected terminal + type because function keys sequences can't be defined in + key map. + + Also be shure to set correct console terminal type in + /etc/ttys for all + ttyv* entries. + Current pre-defined correspondences are: + + + + + + Character Set + Terminal Type + + + + + ISO-8859-1 or ISO-8859-15 + cons25l1 + + + + ISO-8859-2 + cons25l2 + + + + KOI8-R + cons25r + + + + CP437 (hardware default) + cons25 + + + + + - For 8-bit languages, use the correct FreeBSD Port in your + For 16-bit wide languages, use the correct FreeBSD Port in your /usr/ports/language directory. Some ports appear as console while the systems sees it as serial vtty's, hence you must reserve enough vtty's for both X11 and the pseudo-serial console. Here is a partial list of applications for using other languages in console: Language Location Traditional Chinese (BIG-5) /usr/ports/chinese/big5con Japanese /usr/ports/japanese/ja-kon2-* or /usr/ports/japanese/Mule_Wnn Korean /usr/ports/korean/ko-han - - Russian or other KOI8 charsets - cons25r (screenmap and keymap) - - - - Most ISO-8859 charsets - cons2551 - - + - - X11 + + X11 Setup Although X11 is not part of the FreeBSD Project, we have included some information here for FreeBSD users. For more details, refer to the XFree86 website or whichever X11 Server you use. - - Displaying Language Fonts + In ~/.Xresources, you can + additionly tune + application specific i18n settings (e.g., fonts, menus, + etc.). + + + Displaying Fonts Install the X11 True Type-Common server (XTT-common) and install the language truetype fonts. Setting the correct locale should allow you to view your selected language in menus and such. - + - + Inputting Non-English Characters The X11 Input Method (XIM) Protocol is a new standard for all X11 clients. All X11 applications should be written as XIM clients that take input from XIM Input servers. There are several XIM servers available for different languages. - - + + - + Printer Setup - 7-bit characters are usually hardware coded into printers. - 8-bit characters require special setup and we recommend using - apsfilter. You may also convert the document to postscript or - pdf formats using language specific converters. - + 8-bit characters are usually hardware coded into printers. + 16-bit characters require special setup and we recommend using + apsfilter. + You may also convert the document to Postscript or + PDF formats using language specific converters. + - + Kernel and File Systems - To use non-English characters (including 7- and 8-bit - charsets) in the FreeBSD FFS filesystem, kernel patches are - necessary. Otherwise, you may not be able to access the files. - This is language specific, and we ask you again to view related - documentation. - - Some languages are supported in &man.fstab.5;. - - + FreeBSD FFS filesystem is 8-bit clean so can be used + with any 8-bit wide character set, but there is no character + set name stored in filesystem, i.e. it is raw 8-bit and not + knows anything about encoding order. FFS not support any + form of 16-bit wide character sets yet. + + + FreeBSD MSDOS filesystem have configurable + ability to proceed conversion between + MSDOS plus Unicode character sets and choosed + FreeBSD filesystem character set, see + &man.mount_msdos.8; for details. + Advanced Topics If you wish to compile i18n applications or program i18n compliant applications, please read this section. Compiling i18n Programs Many FreeBSD Ports have been ported with i18n support. Some of them are marked with -i18n in the port name. These and many other programs have built in support for i18n and need no special consideration. However, some applications such as MySQL need to be have the Makefile configured with the specific charset. This is usually done in the Makefile or done by passing a value to configure in the source. Programming i18n Compliant Applications To make your application more useful for speakers of other languages, we hope that you will program i18n compliant. The GNU gcc compiler, GUI Libraries like QT and GTK support i18n through special handling of strings. Making a program i18n compliant is very easy. It allows contributors to port your application to other languages quickly. Refer to library specific i18n documentation for more details. To the contrary of common perception, i18n compliant code is easy to write. Usually, it only involves wrapping your strings with library specific functions. In addition, please be sure to - allow for 8-bit character support. + allow for 16-bit wide character support. A Call to Unify the i18n effort It has come to our attention that the individual i18n/l10n efforts for each country has been repeating each others' efforts. Many of us have been reinventing the wheel repeatedly and inefficiently. We hope that the various major groups in i18n could congregate into a group effort similiar to the Core Team's responsibility. Currently, we hope that, when you write or port i18n programs, you would send it out to each country's related FreeBSD mailing lists for testing. In the future, we hope to create applications that work in all the languages out-of-the-box without dirty hacks. Perl and Python - Perl and Python have i18n and 8-bit character handling + Perl and Python have i18n and 16-bit wide character handling libraries. Please use them for i18n compliance. - Occasionally, Perl gives warning about not having a locale + In older FreeBSD versions, + Perl may gives warning about not having a 16-bit wide locale that is already installed in your system. You can set the environmental variable LD_PRELOAD to /usr/lib/libxpg4.so in your shell. In sh-based shells: LD_PRELOAD=/usr/lib/libxpg4.so In C-based shells: setenv LD_PRELOAD /usr/lib/libxpg4.so - Examples for Localizing FreeBSD + Localizing FreeBSD to Specific Language Russian Language (KOI8-R encoding) Originally contributed by &a.ache;. See more info about KOI8-R encoding at KOI8-R References + url="http://nagual.pp.ru/~ache/koi8.html">KOI8-R References (Russian Net Character Set). - See earlier in this chapter for examples of setting up the - console and locale. + + Locale Setup + + Put following lines into + your ~/.login_conf + file: + + +me:My Account:\ + :charset=KOI8-R:\ + :lang=ru_RU.KOI8-R: + + See earlier in this chapter for examples of setting up the + locale. + + + + Console Setup + + + + + Add + + +options SC_MOUSE_CHAR=0x03 + + to your kernel configuration file. + + + + Use following settings in + /etc/rc.conf: + +keymap="ru.koi8-r" +keychange="61 ^[[K" +cursor="destructive" +scrnmap="koi8-r2cp866" +font8x16="cp866b-8x16" +font8x14="cp866-8x14" +font8x8="cp866-8x8" + + Note that ^[ here stands for real + Escape character \033 entered directly in + /etc/rc.conf, not for sequence of two + characters '^' and '['. + + + + For each ttyv* entry in + /etc/ttys use cons25r + as terminal type. + + + + + See earlier in this chapter for examples of setting up the + console. + + Printer Setup Since most printers with Russian characters come with hardware code page CP866, a special output filter is needed for KOI8-R -> CP866 conversion. Such a filter is installed by default as /usr/libexec/lpr/ru/koi2alt. A Russian printer /etc/printcap entry should look like: 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: See &man.printcap.5; for a detailed description. MSDOS FS and Russian Filenames The following example &man.fstab.5; entry enables support for Russian filenames in mounted MSDOS filesystems: -/dev/sd0s1 /dos/c msdos rw,-W=koi2dos,-L=ru_RU.KOI8-R 0 0 +/dev/ad0s2 /dos/c msdos rw,-W=koi2dos,-L=ru_RU.KOI8-R 0 0 - See &man.mount.msdos.8; for a detailed description of the + See &man.mount_msdos.8; for a detailed description of the and options. X11 Setup Do non-X locale setup first as described. The Russian KOI8-R locale may not work with old XFree86 releases (lower than 3.3). The XFree86 port from /usr/ports/x11/XFree86 already is the most recent XFree86 version, so it will work if you install XFree86 from the port. This should not be an issue unless you are using an old version of FreeBSD. Go to the /usr/ports/russian/X.language directory and issue the following command: &prompt.root; make install The above port installs the latest version of the KOI8-R fonts. XFree86 3.3 already has some KOI8-R fonts, but these are scaled better. - Check the “Files” section - in your XF86Config file. The following + Check the "Files" section + in your /etc/XF86Config file. + The following lines must be added before any other FontPath entries: -FontPath “/usr/X11R6/lib/X11/fonts/cyrillic/misc” -FontPath “/usr/X11R6/lib/X11/fonts/cyrillic/75dpi” -FontPath “/usr/X11R6/lib/X11/fonts/cyrillic/100dpi” +FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/misc" +FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi" +FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi" If you use a high resolution video mode, swap the 75 dpi and 100 dpi lines. To activate a Russian keyboard add a - XkbKeymap “xfree86(ru)” - line into the “Keyboard” - section in your XF86Config file. Also + XkbKeymap "xfree86(ru)" + line into the "Keyboard" + section in your /etc/XF86Config file. Also make sure that XkbDisable is turned off (commented out) there. The RUS/LAT switch will be CapsLock. The old CapsLock function is still available via Shift+CapsLock (in LAT mode only). The Russian XKB keyboard may not work with old XFree86 versions, see the above note for more information. The Russian XKB keyboard may also not work with non-localized applications as well. Minimally localized applications should call a XtSetLanguageProc (NULL, NULL, - NULL); function early in the program. + NULL); function early in the program. + See + KOI8-R for X-Window for more + instructions for localizing X11 applications. Traditional Chinese Localization for Taiwan The FreeBSD-Taiwan Project has an i18n/l10n tutorial for FreeBSD at http://freebsd.sinica.edu.tw/~ncvs/zh-l10n-tut/index.html using many /usr/ports/chinese/* applications. The editor for the zh-l10n-tut is Clive Lin Clive@CirX.org. You can also cvsup the following collections at freebsd.sinica.edu.tw: Collection Description outta-port tag=. Beta-quality Ports Collection for Chinese zh-l10n-tut tag=. Localizing FreeBSD Tutorial in BIG-5 Traditional Chinese zh-doc tag=. FreeBSD Documenation Translation to BIG-5 Traditional Chinese Chuan-Hsing Shen s874070@mail.yzu.edu.tw has created the Chinese FreeBSD Extension (CFE) using FreeBSD-Taiwan's zh-l10n-tut. The packages and the script files are available at ftp://ftp-cnpa.yzu.edu.tw/FreeBSD/collect/cfe/cfe.txt and ftp://ftp-cnpa.yzu.edu.tw/FreeBSD/collect/cfe/. German Language Localization (For All ISO 8859-1 Languages) Slaven Rezic eserte@cs.tu-berlin.de wrote a tutorial how to use umlauts on a FreeBSD machine. The tutorial is written in German and available at http://www.de.FreeBSD.org/de/umlaute/. Japanese and Korean Language Localization For Japanese, refer to http://www.jp.FreeBSD.org/, and for Korean, refer to http://www.kr.FreeBSD.org/. Non-English FreeBSD Documentation Some FreeBSD contributors have translated parts of FreeBSD to other languages. They are available through links on the main site or in + url="../">main site or in /usr/share/doc. diff --git a/en_US.ISO_8859-1/books/handbook/l10n/chapter.sgml b/en_US.ISO_8859-1/books/handbook/l10n/chapter.sgml index 9d9747f835..2b49829d29 100644 --- a/en_US.ISO_8859-1/books/handbook/l10n/chapter.sgml +++ b/en_US.ISO_8859-1/books/handbook/l10n/chapter.sgml @@ -1,735 +1,915 @@ Localization - I18N/L10N Usage and Setup Rewritten by Michael Chin-Yuan Wu keichii@mail.utexas.edu, 6 March 2000. Synopsis This section of the handbook discusses the internationalization and localization of FreeBSD to different countries and different settings. If the users wish to use languages other than the system default English, he/she will have to setup the system accordingly. Please note that language support for each language varies in level. Hence, the user should contact the respective FreeBSD local group that is responsible for each language. The author realizes that he may have been incomplete in the description of the i18n process in FreeBSD. Due to the various levels of i18n implementation in both the system and applicational levels, we advise you to refer to individual documentation, man pages, READMEs, and so forth. Should you have any questions or suggestions regarding this chapter, please email the author. The Basics What is i18n/l10n? Developers shortened internationalization into the term i18n, counting the number of letters between the first and the last letters of internationalization. l10n uses the same naming - scheme, coming from “localization”. Combined + scheme, coming from "localization". Combined together, i18n/l10n methods, protocols, and applications allow users to use languages of their choice. I18n applications are programmed using i18n kits under libraries. It allows for developers to write a simple file and translate displayed menus and texts to each language. We strongly encourage programmers to follow this convention. Why should I use i18n/l10n? I18n/l10n is used whenever you wish to either view, input, or process data in non-English languages. What languages are supported in the i18n effort? I18n and l10n are not FreeBSD specific. Currently, one can choose from most of the major languages of the World, including but not limited to: Chinese, German, Japanese, French, Russian, and others. Using Localization In all its splendor, i18n is not FreeBSD-specific and is a convention. We encourage you to help FreeBSD in following this convention. + Localization settings are based on three main terms: + Language Code, Country Code and Encoding. Locale name constructed + with this three parts as follows: + + +LanguageCode_CountryCode.Encoding + - Language Codes + Language and Country Codes In order to localize a FreeBSD system to a specific language (or any other i18n-supporting UNIX's), the user needs to find out - the language code for the specify country and language. Country - codes tell applications what language to use. In addition, web + the codes for the specify country and language (country + codes tell applications what variation of given + language to use). In addition, web browsers, SMTP/POP servers, HTTPd's, etc. make decisions based on - them. The following are examples of country codes: + them. The following are examples of language/country codes: - Language code + Language/Country Code Description - en - Generic English - - - - en.us - English—United States + en_US + English - United States - ru - Russian + ru_RU + Russian for Russia - zh_TW.Big5 + zh_TW Traditional Chinese for Taiwan - You can read more about character sets and language codes at - ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets. - Encoding + Encodings - Some languages (mostly Asian ones) use non-ASCII encodings - that are 8-bit characters. Older applications do not recognize + Some languages use non-ASCII encodings + that are 8-bit or 16-bit wide characters. + Older applications do not recognize them and mistake them for control characters. Newer applications + usually do recognize 8-bit characters. Depending on implementation, users - may be required to compile the application with 8-bit support - (such as MySQL and Apache), or configure it correctly (such as - telnet, ssh, and system shells). To be able to input and process - 8-bit characters, the FreeBSD Ports + may be required to compile an application with 16-bit support, + or configure it correctly. + To be able to input and process + 16-bit wide characters, the FreeBSD Ports collection has provided each language with different programs. Refer to the i18n documentation in the respective FreeBSD Port. Specifically, the user needs to look at the application documentation to decide on how to configure it correctly or to pass correct values into the configure/Makefile/compiler. Some things to keep in mind are: - UTF-8 encoding + Language specific 8-bit wide character sets, f.e. + ISO_8859-1, KOI8-R, CP437. - Language specific MIME 8-bit support + 16-bit wide encodings, f.e. EUC, Big5. - - Language specific charsets - - - - UUENCODE/UUDECODE - + + You can check active list of character sets at + IANA Registry. - i18n applications + I18n applications In the FreeBSD Ports and Package system, i18n applications have been named with i18n in their names for easy identification. However, they do not always support the language needed. - Non-English users should install i18n libraries and - applications if they wish to use a different locale. Setting Locale Theoretically, one only needs to export the value of his/her - language code as LANG in the login shell and is usually done - through the user login shell configuration - (.profile, .bashrc, or - .cshrc). This should set all of the locale + locale name as LANG + in the login shell and is usually done + through the user's ~/.login_conf or + the user login shell configuration + (~/.profile, ~/.bashrc, + ~/.cshrc). + This should set all of the locale subsets (such as LC_CTYPE, - LC_CTIME, etc.). However, some applications - that do not follow the i18n convention correctly will require you - to set each locale subset specifically. Please refer to + LC_CTIME, etc.). + Please refer to language-specific FreeBSD documentation for more information. You should set the following two values in your configuration files: LANG for POSIX &man.setlocale.3; family functions MM_CHARSET for applications' MIME character set - This includes the user shell config, the specific library + This includes the user shell config, the specific application config, and the X11 config. - Setting Locale - Shell Startup Files Method - - There are two methods for setting locale, and both are - described below. The first is by adding environment variables - to the system's shell startup files, and the second is by login class. To use th first - method, just set the two environment variables shown below in - the /etc/profile and/or - /etc/csh.login shell startup files. We - will use the Russian language as an example below: - - In /etc/profile: - - -LANG=ru_RU.KOI8-R; export LANG -MM_CHARSET=KOI8-R; export MM_CHARSET - - Or in /etc/csh.login: + Setting Locale Methods + + There are two methods for setting locale, and both are + described below. The first (recommended one) is by + setting environment variables assignment in + login class, + and the second is by adding environment variables assignment + to the system's shell + startup file. + + + Login Classes Method + + This method allows to assing environment + variables needed for locale name and MIME character set once + for every possible shell instead of adding specific shell assignment + to each shell startup file. + User Level Setup + can be done by an user himself and + Administrator Level Setup require + superuser priviledges. + + + User Level Setup + + Here is minimal example of ~/.login_conf + file in user's home directory which have both variables set + for Russian KOI8-R encoding: -setenv LANG ru_RU.KOI8-R -setenv MM_CHARSET KOI8-R - - Alternatively, you can add the above instructions to - /usr/share/skel/dot.profile (similar to - what was used in /etc/profile above), or - /usr/share/skel/dot.login (similar to what - was used in /etc/csh.login above). - - For X11: - - In $HOME/.xinitrc: - - -LANG=ru_RU.KOI8-R; export LANG - - Or: - - -setenv LANG ru_RU.KOI8-R +me:My Account:\ + :charset=KOI8-R:\ + :lang=ru_RU.KOI8-R: - Depending on your shell (see above). + See + Administrator Level Setup + and + &man.login.conf.5; for explanation. - In $HOME/.Xresources, you can set - application specific i18n settings (e.g., fonts, display - characters, etc.). - + - - Login Classes - - This method of setting locale should only be used when you - wish each user to be using the language you choose for your - system. If you are a user or wish to allow users to default to - English and change locale themselves, please disregard this - section. + + Administrator Level Setup Check that /etc/login.conf have the correct language user's class. Make sure these settings appear in /etc/login.conf: -language:Title for user accounts:\ - :charset=language charset:\ - :lang=country code.charset:\ +language_name:accounts_title:\ + :charset=MIME_charset:\ + :lang=locale_name:\ :tc=default: So sticking with our previous example using Russian, it would look like this: russian:Russian Users Accounts:\ :charset=KOI8-R:\ :lang=ru_RU.KOI8-R:\ :tc=default: - + Changing Login Classes with &man.vipw.8; Use vipw to add new users, and make the entry look like this: user:password:1111:11:language:0:0:User Name:/home/user:/bin/sh - + - + Changing Login Classes with &man.adduser.8; Use adduser to add new users, and do the following: Set defaultclass = language in /etc/adduser.conf. Keep in mind you must enter default class for all users of other languages in this case. An alternative variant is answering the specified language each time that Enter login class: default []: appears from &man.adduser.8; Another alternative is to use the following for each user of a different language that you wish to add: &prompt.root; adduser -class language - + - + Changing Login Classes with &man.pw.8; If you use &man.pw.8; for adding new users, call it in this form: - &prompt.root; pw useradd user_name -L language - + &prompt.root; pw useradd user_name -L language + + + + + + Shell Startup File Method + + + This method is not recommended because require + different setup for each possible login program choosed. + Use Login Class Method + instead. + + + To add locale name and MIME character set + just set the two environment variables shown below in + the /etc/profile and/or + /etc/csh.login shell startup files. We + will use the Russian language as an example below: + + In /etc/profile: + + +LANG=ru_RU.KOI8-R; export LANG +MM_CHARSET=KOI8-R; export MM_CHARSET + + Or in /etc/csh.login: + + +setenv LANG ru_RU.KOI8-R +setenv MM_CHARSET KOI8-R + + Alternatively, you can add the above instructions to + /usr/share/skel/dot.profile (similar to + what was used in /etc/profile above), or + /usr/share/skel/dot.login (similar to what + was used in /etc/csh.login above). + + For X11: + + In $HOME/.xinitrc: + + +LANG=ru_RU.KOI8-R; export LANG + + Or: + + +setenv LANG ru_RU.KOI8-R + + Depending on your shell (see above). + + + + - - Console + + Console Setup - For all 7-bit Roman languages, set the correct console fonts + For all 8-bit wide languages, set the correct console fonts in /etc/rc.conf for the language in question with: -font8x16=font name -font8x14=font name -font8x8=font name +font8x16=font_name +font8x14=font_name +font8x8=font_name + + font_name here taken from + /usr/share/syscons/fonts directory, + without .fnt suffix. Also be sure to set the correct keymap and screenmap for - your 7-bit language through + your 8-bit language through /stand/sysinstall. Once inside sysinstall, choose Configure, then Console. Alternatively, you can add the following to /etc/rc.conf: -scrnmap=screenmap name -keychange=special key names -keymap=keymap name +scrnmap=screenmap_name +keymap=keymap_name +keychange="fkey_number sequence" + + screenmap_name here taken from + /usr/share/syscons/scrnmaps directory, + without .scm suffix. + Screenmap with corresponding mapped font + is usually needed as workaround for expanding + 8-bit to 9-bit on VGA adapters in pseudographics area, i.e. + to move characters out of that area. + + If you use destructive type of cursor + like following setting in /etc/rc.conf: + + +cursor="destructive" + + (see &man.vidcontrol.1;) + be shure that you compile your kernel with + + +options SC_MOUSE_CHAR=0x03 + + in your kernel configuration file to avoid + 8-bit to 9-bit expansion of mouse cursor image on VGA adapters. + + + keymap_name here taken from + /usr/share/syscons/keymaps directory, + without .kbd suffix. + + keychange is usually needed + to program function keys to match selected terminal + type because function keys sequences can't be defined in + key map. + + Also be shure to set correct console terminal type in + /etc/ttys for all + ttyv* entries. + Current pre-defined correspondences are: + + + + + + Character Set + Terminal Type + + + + + ISO-8859-1 or ISO-8859-15 + cons25l1 + + + + ISO-8859-2 + cons25l2 + + + + KOI8-R + cons25r + + + + CP437 (hardware default) + cons25 + + + + + - For 8-bit languages, use the correct FreeBSD Port in your + For 16-bit wide languages, use the correct FreeBSD Port in your /usr/ports/language directory. Some ports appear as console while the systems sees it as serial vtty's, hence you must reserve enough vtty's for both X11 and the pseudo-serial console. Here is a partial list of applications for using other languages in console: Language Location Traditional Chinese (BIG-5) /usr/ports/chinese/big5con Japanese /usr/ports/japanese/ja-kon2-* or /usr/ports/japanese/Mule_Wnn Korean /usr/ports/korean/ko-han - - Russian or other KOI8 charsets - cons25r (screenmap and keymap) - - - - Most ISO-8859 charsets - cons2551 - - + - - X11 + + X11 Setup Although X11 is not part of the FreeBSD Project, we have included some information here for FreeBSD users. For more details, refer to the XFree86 website or whichever X11 Server you use. - - Displaying Language Fonts + In ~/.Xresources, you can + additionly tune + application specific i18n settings (e.g., fonts, menus, + etc.). + + + Displaying Fonts Install the X11 True Type-Common server (XTT-common) and install the language truetype fonts. Setting the correct locale should allow you to view your selected language in menus and such. - + - + Inputting Non-English Characters The X11 Input Method (XIM) Protocol is a new standard for all X11 clients. All X11 applications should be written as XIM clients that take input from XIM Input servers. There are several XIM servers available for different languages. - - + + - + Printer Setup - 7-bit characters are usually hardware coded into printers. - 8-bit characters require special setup and we recommend using - apsfilter. You may also convert the document to postscript or - pdf formats using language specific converters. - + 8-bit characters are usually hardware coded into printers. + 16-bit characters require special setup and we recommend using + apsfilter. + You may also convert the document to Postscript or + PDF formats using language specific converters. + - + Kernel and File Systems - To use non-English characters (including 7- and 8-bit - charsets) in the FreeBSD FFS filesystem, kernel patches are - necessary. Otherwise, you may not be able to access the files. - This is language specific, and we ask you again to view related - documentation. - - Some languages are supported in &man.fstab.5;. - - + FreeBSD FFS filesystem is 8-bit clean so can be used + with any 8-bit wide character set, but there is no character + set name stored in filesystem, i.e. it is raw 8-bit and not + knows anything about encoding order. FFS not support any + form of 16-bit wide character sets yet. + + + FreeBSD MSDOS filesystem have configurable + ability to proceed conversion between + MSDOS plus Unicode character sets and choosed + FreeBSD filesystem character set, see + &man.mount_msdos.8; for details. + Advanced Topics If you wish to compile i18n applications or program i18n compliant applications, please read this section. Compiling i18n Programs Many FreeBSD Ports have been ported with i18n support. Some of them are marked with -i18n in the port name. These and many other programs have built in support for i18n and need no special consideration. However, some applications such as MySQL need to be have the Makefile configured with the specific charset. This is usually done in the Makefile or done by passing a value to configure in the source. Programming i18n Compliant Applications To make your application more useful for speakers of other languages, we hope that you will program i18n compliant. The GNU gcc compiler, GUI Libraries like QT and GTK support i18n through special handling of strings. Making a program i18n compliant is very easy. It allows contributors to port your application to other languages quickly. Refer to library specific i18n documentation for more details. To the contrary of common perception, i18n compliant code is easy to write. Usually, it only involves wrapping your strings with library specific functions. In addition, please be sure to - allow for 8-bit character support. + allow for 16-bit wide character support. A Call to Unify the i18n effort It has come to our attention that the individual i18n/l10n efforts for each country has been repeating each others' efforts. Many of us have been reinventing the wheel repeatedly and inefficiently. We hope that the various major groups in i18n could congregate into a group effort similiar to the Core Team's responsibility. Currently, we hope that, when you write or port i18n programs, you would send it out to each country's related FreeBSD mailing lists for testing. In the future, we hope to create applications that work in all the languages out-of-the-box without dirty hacks. Perl and Python - Perl and Python have i18n and 8-bit character handling + Perl and Python have i18n and 16-bit wide character handling libraries. Please use them for i18n compliance. - Occasionally, Perl gives warning about not having a locale + In older FreeBSD versions, + Perl may gives warning about not having a 16-bit wide locale that is already installed in your system. You can set the environmental variable LD_PRELOAD to /usr/lib/libxpg4.so in your shell. In sh-based shells: LD_PRELOAD=/usr/lib/libxpg4.so In C-based shells: setenv LD_PRELOAD /usr/lib/libxpg4.so - Examples for Localizing FreeBSD + Localizing FreeBSD to Specific Language Russian Language (KOI8-R encoding) Originally contributed by &a.ache;. See more info about KOI8-R encoding at KOI8-R References + url="http://nagual.pp.ru/~ache/koi8.html">KOI8-R References (Russian Net Character Set). - See earlier in this chapter for examples of setting up the - console and locale. + + Locale Setup + + Put following lines into + your ~/.login_conf + file: + + +me:My Account:\ + :charset=KOI8-R:\ + :lang=ru_RU.KOI8-R: + + See earlier in this chapter for examples of setting up the + locale. + + + + Console Setup + + + + + Add + + +options SC_MOUSE_CHAR=0x03 + + to your kernel configuration file. + + + + Use following settings in + /etc/rc.conf: + +keymap="ru.koi8-r" +keychange="61 ^[[K" +cursor="destructive" +scrnmap="koi8-r2cp866" +font8x16="cp866b-8x16" +font8x14="cp866-8x14" +font8x8="cp866-8x8" + + Note that ^[ here stands for real + Escape character \033 entered directly in + /etc/rc.conf, not for sequence of two + characters '^' and '['. + + + + For each ttyv* entry in + /etc/ttys use cons25r + as terminal type. + + + + + See earlier in this chapter for examples of setting up the + console. + + Printer Setup Since most printers with Russian characters come with hardware code page CP866, a special output filter is needed for KOI8-R -> CP866 conversion. Such a filter is installed by default as /usr/libexec/lpr/ru/koi2alt. A Russian printer /etc/printcap entry should look like: 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: See &man.printcap.5; for a detailed description. MSDOS FS and Russian Filenames The following example &man.fstab.5; entry enables support for Russian filenames in mounted MSDOS filesystems: -/dev/sd0s1 /dos/c msdos rw,-W=koi2dos,-L=ru_RU.KOI8-R 0 0 +/dev/ad0s2 /dos/c msdos rw,-W=koi2dos,-L=ru_RU.KOI8-R 0 0 - See &man.mount.msdos.8; for a detailed description of the + See &man.mount_msdos.8; for a detailed description of the and options. X11 Setup Do non-X locale setup first as described. The Russian KOI8-R locale may not work with old XFree86 releases (lower than 3.3). The XFree86 port from /usr/ports/x11/XFree86 already is the most recent XFree86 version, so it will work if you install XFree86 from the port. This should not be an issue unless you are using an old version of FreeBSD. Go to the /usr/ports/russian/X.language directory and issue the following command: &prompt.root; make install The above port installs the latest version of the KOI8-R fonts. XFree86 3.3 already has some KOI8-R fonts, but these are scaled better. - Check the “Files” section - in your XF86Config file. The following + Check the "Files" section + in your /etc/XF86Config file. + The following lines must be added before any other FontPath entries: -FontPath “/usr/X11R6/lib/X11/fonts/cyrillic/misc” -FontPath “/usr/X11R6/lib/X11/fonts/cyrillic/75dpi” -FontPath “/usr/X11R6/lib/X11/fonts/cyrillic/100dpi” +FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/misc" +FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi" +FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi" If you use a high resolution video mode, swap the 75 dpi and 100 dpi lines. To activate a Russian keyboard add a - XkbKeymap “xfree86(ru)” - line into the “Keyboard” - section in your XF86Config file. Also + XkbKeymap "xfree86(ru)" + line into the "Keyboard" + section in your /etc/XF86Config file. Also make sure that XkbDisable is turned off (commented out) there. The RUS/LAT switch will be CapsLock. The old CapsLock function is still available via Shift+CapsLock (in LAT mode only). The Russian XKB keyboard may not work with old XFree86 versions, see the above note for more information. The Russian XKB keyboard may also not work with non-localized applications as well. Minimally localized applications should call a XtSetLanguageProc (NULL, NULL, - NULL); function early in the program. + NULL); function early in the program. + See + KOI8-R for X-Window for more + instructions for localizing X11 applications. Traditional Chinese Localization for Taiwan The FreeBSD-Taiwan Project has an i18n/l10n tutorial for FreeBSD at http://freebsd.sinica.edu.tw/~ncvs/zh-l10n-tut/index.html using many /usr/ports/chinese/* applications. The editor for the zh-l10n-tut is Clive Lin Clive@CirX.org. You can also cvsup the following collections at freebsd.sinica.edu.tw: Collection Description outta-port tag=. Beta-quality Ports Collection for Chinese zh-l10n-tut tag=. Localizing FreeBSD Tutorial in BIG-5 Traditional Chinese zh-doc tag=. FreeBSD Documenation Translation to BIG-5 Traditional Chinese Chuan-Hsing Shen s874070@mail.yzu.edu.tw has created the Chinese FreeBSD Extension (CFE) using FreeBSD-Taiwan's zh-l10n-tut. The packages and the script files are available at ftp://ftp-cnpa.yzu.edu.tw/FreeBSD/collect/cfe/cfe.txt and ftp://ftp-cnpa.yzu.edu.tw/FreeBSD/collect/cfe/. German Language Localization (For All ISO 8859-1 Languages) Slaven Rezic eserte@cs.tu-berlin.de wrote a tutorial how to use umlauts on a FreeBSD machine. The tutorial is written in German and available at http://www.de.FreeBSD.org/de/umlaute/. Japanese and Korean Language Localization For Japanese, refer to http://www.jp.FreeBSD.org/, and for Korean, refer to http://www.kr.FreeBSD.org/. Non-English FreeBSD Documentation Some FreeBSD contributors have translated parts of FreeBSD to other languages. They are available through links on the main site or in + url="../">main site or in /usr/share/doc.