| blob | 97bb31a56c46d402601ddb246b804de804363f93 |
1 .\" $NetBSD: nls.7,v 1.11 2003/06/26 11:55:56 wiz Exp $
2 .\"
3 .\" Copyright (c) 2003 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Gregory McGarry.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\" 3. All advertising materials mentioning features or use of this software
18 .\" must display the following acknowledgement:
19 .\" This product includes software developed by the NetBSD
20 .\" Foundation, Inc. and its contributors.
21 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
22 .\" contributors may be used to endorse or promote products derived
23 .\" from this software without specific prior written permission.
24 .\"
25 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35 .\" POSSIBILITY OF SUCH DAMAGE.
36 .\"
37 .\" $DragonFly: src/share/man/man7/nls.7,v 1.7 2008/05/02 02:05:06 swildner Exp $
38 .\"
39 .Dd May 17, 2003
40 .Dt NLS 7
41 .Os
42 .Sh NAME
43 .Nm NLS
44 .Nd Native Language Support Overview
45 .Sh DESCRIPTION
46 Native Language Support (NLS) provides commands for a single
47 worldwide operating system base.
48 An internationalized system has no built-in assumptions or dependencies
49 on language-specific or cultural-specific conventions such as:
50 .Pp
51 .Bl -bullet -offset indent -compact
52 .It
53 Character classifications
54 .It
55 Character comparison rules
56 .It
57 Character collation order
58 .It
59 Numeric and monetary formatting
60 .It
61 Date and time formatting
62 .It
63 Message-text language
64 .It
65 Character sets
66 .El
67 .Pp
68 All information pertaining to cultural conventions and language is
69 obtained at program run time.
70 .Pp
71 .Dq Internationalization
72 (often abbreviated
73 .Dq i18n )
74 refers to the operation by which system software is developed to support
75 multiple cultural-specific and language-specific conventions.
76 This is a generalization process by which the system is untied from
77 calling only English strings or other English-specific conventions.
78 .Dq Localization
79 (often abbreviated
80 .Dq l10n )
81 refers to the operations by which the user environment is customized to
82 handle its input and output appropriate for specific language and cultural
83 conventions.
84 This is a specialization process, by which generic methods already
85 implemented in an internationalized system are used in specific ways.
86 The formal description of cultural conventions for some country, together
87 with all associated translations targeted to the native language, is
88 called the
89 .Dq locale .
90 .Pp
91 .Dx
92 provides extensive support to programmers and system developers to
93 enable internationalized software to be developed.
94 .Dx
95 also supplies a large variety of locales for system localization.
96 .Ss Localization of Information
97 All locale information is accessible to programs at run time so that
98 data is processed and displayed correctly for specific cultural
99 conventions and language.
100 .Pp
101 A locale is divided into categories.
102 A category is a group of language-specific and culture-specific conventions
103 as outlined in the list above.
104 ISO C specifies the following six standard categories supported by
105 .Dx :
106 .Pp
107 .Bl -tag -compact -width LC_MONETARYXX
108 .It LC_COLLATE
109 string-collation order information
110 .It LC_CTYPE
111 character classification, case conversion, and other character attributes
112 .It LC_MESSAGES
113 the format for affirmative and negative responses
114 .It LC_MONETARY
115 rules and symbols for formatting monetary numeric information
116 .It LC_NUMERIC
117 rules and symbols for formatting nonmonetary numeric information
118 .It LC_TIME
119 rules and symbols for formatting time and date information
120 .El
121 .Pp
122 Localization of the system is achieved by setting appropriate values
123 in environment variables to identify which locale should be used.
124 The environment variables have the same names as their respective
125 locale categories.
126 Additionally, the
127 .Ev LANG ,
128 .Ev LC_ALL ,
129 and
130 .Ev NLSPATH
131 environment variables are used.
132 The
133 .Ev NLSPATH
134 environment variable specifies a colon-separated list of directory names
135 where the message catalog files of the NLS database are located.
136 The
137 .Ev LC_ALL
138 and
139 .Ev LANG
140 environment variables also determine the current locale.
141 .Pp
142 The values of these environment variables contains a string format as:
143 .Bd -literal
144 language[_territory][.codeset][@modifier]
145 .Ed
146 .Pp
147 Valid values for the language field come from the ISO639 standard which
148 defines two-character codes for many languages.
149 Some common language codes are:
150 .Pp
151 .nf
152 .ta \w'SERBO-CROATIAN'u+2n +\w'DE'u+5n +\w'OCEANIC/INDONESIAN'u+2nC
153 \fILanguage Name\fP \fICode\fP \fILanguage Family\fP
154 .ta \w'SERBO-CROATIAN'u+2n +\w'DE'u+5n +\w'OCEANIC/INDONESIAN'u+2nC
155 .sp 5p
156 ABKHAZIAN AB IBERO-CAUCASIAN
157 AFAN (OROMO) OM HAMITIC
158 AFAR AA HAMITIC
159 AFRIKAANS AF GERMANIC
160 ALBANIAN SQ INDO-EUROPEAN (OTHER)
161 AMHARIC AM SEMITIC
162 ARABIC AR SEMITIC
163 ARMENIAN HY INDO-EUROPEAN (OTHER)
164 ASSAMESE AS INDIAN
165 AYMARA AY AMERINDIAN
166 AZERBAIJANI AZ TURKIC/ALTAIC
167 BASHKIR BA TURKIC/ALTAIC
168 BASQUE EU BASQUE
169 BENGALI BN INDIAN
170 BHUTANI DZ ASIAN
171 BIHARI BH INDIAN
172 BISLAMA BI
173 BRETON BR CELTIC
174 BULGARIAN BG SLAVIC
175 BURMESE MY ASIAN
176 BYELORUSSIAN BE SLAVIC
177 CAMBODIAN KM ASIAN
178 CATALAN CA ROMANCE
179 CHINESE ZH ASIAN
180 CORSICAN CO ROMANCE
181 CROATIAN HR SLAVIC
182 CZECH CS SLAVIC
183 DANISH DA GERMANIC
184 DUTCH NL GERMANIC
185 ENGLISH EN GERMANIC
186 ESPERANTO EO INTERNATIONAL AUX.
187 ESTONIAN ET FINNO-UGRIC
188 FAROESE FO GERMANIC
189 FIJI FJ OCEANIC/INDONESIAN
190 FINNISH FI FINNO-UGRIC
191 FRENCH FR ROMANCE
192 FRISIAN FY GERMANIC
193 GALICIAN GL ROMANCE
194 GEORGIAN KA IBERO-CAUCASIAN
195 GERMAN DE GERMANIC
196 GREEK EL LATIN/GREEK
197 GREENLANDIC KL ESKIMO
198 GUARANI GN AMERINDIAN
199 GUJARATI GU INDIAN
200 HAUSA HA NEGRO-AFRICAN
201 HEBREW HE SEMITIC
202 HINDI HI INDIAN
203 HUNGARIAN HU FINNO-UGRIC
204 ICELANDIC IS GERMANIC
205 INDONESIAN ID OCEANIC/INDONESIAN
206 INTERLINGUA IA INTERNATIONAL AUX.
207 INTERLINGUE IE INTERNATIONAL AUX.
208 INUKTITUT IU
209 INUPIAK IK ESKIMO
210 IRISH GA CELTIC
211 ITALIAN IT ROMANCE
212 JAPANESE JA ASIAN
213 JAVANESE JV OCEANIC/INDONESIAN
214 KANNADA KN DRAVIDIAN
215 KASHMIRI KS INDIAN
216 KAZAKH KK TURKIC/ALTAIC
217 KINYARWANDA RW NEGRO-AFRICAN
218 KIRGHIZ KY TURKIC/ALTAIC
219 KURUNDI RN NEGRO-AFRICAN
220 KOREAN KO ASIAN
221 KURDISH KU IRANIAN
222 LAOTHIAN LO ASIAN
223 LATIN LA LATIN/GREEK
224 LATVIAN LV BALTIC
225 LINGALA LN NEGRO-AFRICAN
226 LITHUANIAN LT BALTIC
227 MACEDONIAN MK SLAVIC
228 MALAGASY MG OCEANIC/INDONESIAN
229 MALAY MS OCEANIC/INDONESIAN
230 MALAYALAM ML DRAVIDIAN
231 MALTESE MT SEMITIC
232 MAORI MI OCEANIC/INDONESIAN
233 MARATHI MR INDIAN
234 MOLDAVIAN MO ROMANCE
235 MONGOLIAN MN
236 NAURU NA
237 NEPALI NE INDIAN
238 NORWEGIAN NO GERMANIC
239 OCCITAN OC ROMANCE
240 ORIYA OR INDIAN
241 PASHTO PS IRANIAN
242 PERSIAN (farsi) FA IRANIAN
243 POLISH PL SLAVIC
244 PORTUGUESE PT ROMANCE
245 PUNJABI PA INDIAN
246 QUECHUA QU AMERINDIAN
247 RHAETO-ROMANCE RM ROMANCE
248 ROMANIAN RO ROMANCE
249 RUSSIAN RU SLAVIC
250 SAMOAN SM OCEANIC/INDONESIAN
251 SANGHO SG NEGRO-AFRICAN
252 SANSKRIT SA INDIAN
253 SCOTS GAELIC GD CELTIC
254 SERBIAN SR SLAVIC
255 SERBO-CROATIAN SH SLAVIC
256 SESOTHO ST NEGRO-AFRICAN
257 SETSWANA TN NEGRO-AFRICAN
258 SHONA SN NEGRO-AFRICAN
259 SINDHI SD INDIAN
260 SINGHALESE SI INDIAN
261 SISWATI SS NEGRO-AFRICAN
262 SLOVAK SK SLAVIC
263 SLOVENIAN SL SLAVIC
264 SOMALI SO HAMITIC
265 SPANISH ES ROMANCE
266 SUNDANESE SU OCEANIC/INDONESIAN
267 SWAHILI SW NEGRO-AFRICAN
268 SWEDISH SV GERMANIC
269 TAGALOG TL OCEANIC/INDONESIAN
270 TAJIK TG IRANIAN
271 TAMIL TA DRAVIDIAN
272 TATAR TT TURKIC/ALTAIC
273 TELUGU TE DRAVIDIAN
274 THAI TH ASIAN
275 TIBETAN BO ASIAN
276 TIGRINYA TI SEMITIC
277 TONGA TO OCEANIC/INDONESIAN
278 TSONGA TS NEGRO-AFRICAN
279 TURKISH TR TURKIC/ALTAIC
280 TURKMEN TK TURKIC/ALTAIC
281 TWI TW NEGRO-AFRICAN
282 UIGUR UG
283 UKRAINIAN UK SLAVIC
284 URDU UR INDIAN
285 UZBEK UZ TURKIC/ALTAIC
286 VIETNAMESE VI ASIAN
287 VOLAPUK VO INTERNATIONAL AUX.
288 WELSH CY CELTIC
289 WOLOF WO NEGRO-AFRICAN
290 XHOSA XH NEGRO-AFRICAN
291 YIDDISH YI GERMANIC
292 YORUBA YO NEGRO-AFRICAN
293 ZHUANG ZA
294 ZULU ZU NEGRO-AFRICAN
295 .ta
296 .fi
297 .Pp
298 For example, the locale for the Danish language spoken in Denmark
299 using the ISO8859-1 character set is da_DK.ISO8859-1.
300 The da stands for the Danish language and the DK stands for Denmark.
301 The short form of da_DK is sufficient to indicate this locale.
302 .Pp
303 The environment variable settings are queried by their priority level
304 in the following manner:
305 .Bl -bullet
306 .It
307 If the
308 .Ev LC_ALL
309 environment variable is set, all six categories use the locale it
310 specifies.
311 .It
312 If the
313 .Ev LC_ALL
314 environment variable is not set, each individual category uses the
315 locale specified by its corresponding environment variable.
316 .It
317 If the
318 .Ev LC_ALL
319 environment variable is not set, and a value for a particular
320 .Ev LC_*
321 environment variable is not set, the value of the
322 .Ev LANG
323 environment variable specifies the default locale for all categories.
324 Only the
325 .Ev LANG
326 environment variable should be set in /etc/profile, since it makes it
327 most easy for the user to override the system default using the individual
328 .Ev LC_*
329 variables.
330 .It
331 If the
332 .Ev LC_ALL
333 environment variable is not set, a value for a particular
334 .Ev LC_*
335 environment variable is not set, and the value of the
336 .Ev LANG
337 environment variable is not set, the locale for that specific
338 category defaults to the C locale.
339 The C or POSIX locale assumes the 7-bit ASCII character set and defines
340 information for the six categories.
341 .El
342 .Ss Character Sets
343 A character is any symbol used for the organization, control, or
344 representation of data.
345 A group of such symbols used to describe a
346 particular language make up a character set.
347 It is the encoding values in a character set that provide
348 the interface between the system and its input and output devices.
349 .Pp
350 The following character sets are supported in
351 .Dx
352 .Bl -tag -width ISO8859_family
353 .It ISO8859 family
354 Industry-standard character sets are provided by means of the ISO8859
355 family of character sets, which provide a range of single-byte character set
356 support that includes Latin-1, Latin-2, Arabic, Cyrillic, Hebrew,
357 Greek, and Turkish.
358 The eucJP character set is the industry-standard character set used to support
359 the Japanese locale.
360 .It Unicode
361 A Unicode environment based on the UTF-8 character set is supported for all
362 supported language/territories.
363 UTF-8 provides character support for most of the major languages of the
364 world and can be used in environments where multiple languages must be
365 processed simultaneously.
366 .El
367 .Ss Font Sets
368 A font set contains the glyphs to be displayed on the screen for a
369 corresponding character in a character set.
370 A display must support a suitable font to display a character set.
371 If suitable fonts are available to the X server, then X clients can
372 include support for different character sets.
373 .Xr xterm 1
374 includes support for UTF-8 character sets.
375 .Xr xfd 1
376 is useful for displaying all the characters in an X font.
377 .Pp
378 The
379 .Dx
380 .Xr syscons 4
381 console provides support for loading a variety of fonts using the
382 .Xr vidcontrol 1
383 utility. Available fonts can be found in
384 .Pa /usr/share/syscons/fonts .
385 .Ss Internationalization for Programmers
386 To facilitate translations of messages into various languages and to
387 make the translated messages available to the program based on a
388 user's locale, it is necessary to keep messages separate from the
389 programs and provide them in the form of message catalogs that a
390 program can access at run time.
391 .Pp
392 Access to locale information is provided through the
393 .Xr setlocale 3
394 and
395 .Xr nl_langinfo 3
396 interfaces.
397 See their respective man pages for further information.
398 .Pp
399 Message source files containing application messages are created by
400 the programmer and converted to message catalogs.
401 These catalogs are used by the application to retrieve and display
402 messages, as needed.
403 .Pp
404 .Dx
405 supports two message catalog interfaces: the X/Open
406 .Xr catgets 3
407 interface and the Uniforum
408 .Xr gettext 3
409 interface.
410 The
411 .Xr catgets 3
412 interface has the advantage that it belongs to a standard which is
413 well supported.
414 Unfortunately the interface is complicated to use and
415 maintenance of the catalogs is difficult.
416 The implementation also doesn't support different character sets.
417 The
418 .Xr gettext 3
419 interface has not been standardized yet, however it is being supported
420 by an increasing number of systems.
421 It also provides many additional tools which make programming and
422 catalog maintenance much easier.
423 .Ss Support for Multibyte Characters and Wide Characters
424 Character sets with multibyte characters may be difficult to decode, or may
425 contain state (i.e., adjacent characters are dependent).
426 ISO C specifies a set of functions using 'wide characters' which can handle
427 multibyte characters properly.
428 A wide character is specified in ISO C
429 as being a fixed number of bits wide and is stateless.
430 .Pp
431 There are two types for wide characters:
432 .Em wchar_t
433 and
434 .Em wint_t .
435 .Em wchar_t
436 is a type which can contain one wide character and operates like 'char'
437 type does for one character.
438 .Em wint_t
439 can contain one wide character or WEOF (wide EOF).
440 .Pp
441 There are functions that operate on
442 .Em wchar_t ,
443 and substitute for functions operating on 'char'.
444 See
445 .Xr wmemchr 3
446 and
447 .Xr towlower 3
448 for details.
449 There are some additional functions that operate on
450 .Em wchar_t .
451 See
452 .Xr wctype 3
453 and
454 .Xr wctrans 3
455 for details.
456 .Pp
457 Wide characters should be used for all I/O processing which may rely
458 on locale-specific strings.
459 The two primary issues requiring special use of wide characters are:
460 .Bl -bullet -offset indent
461 .It
462 All I/O is performed using multibyte characters.
463 Input data is converted into wide characters immediately after
464 reading and data for output is converted from wide characters to
465 multibyte characters immediately before writing.
466 Conversion is achieved using
467 .Xr mbstowcs 3 ,
468 .Xr mbsrtowcs 3 ,
469 .Xr wcstombs 3 ,
470 .Xr wcsrtombs 3 ,
471 .Xr mblen 3 ,
472 .Xr mbrlen 3 ,
473 and
474 .Xr mbsinit 3 .
475 .It
476 Wide characters are used directly for I/O, using
477 .Xr getwchar 3 ,
478 .Xr fgetwc 3 ,
479 .Xr getwc 3 ,
480 .Xr ungetwc 3 ,
481 .Xr fgetws 3 ,
482 .Xr putwchar 3 ,
483 .Xr fputwc 3 ,
484 .Xr putwc 3 ,
485 and
486 .Xr fputws 3 .
487 They are also used for formatted I/O functions for wide characters
488 such as
489 .Xr fwscanf 3 ,
490 .Xr wscanf 3 ,
491 .Xr swscanf 3 ,
492 .Xr fwprintf 3 ,
493 .Xr wprintf 3 ,
494 .Xr swprintf 3 ,
495 .Xr vfwprintf 3 ,
496 .Xr vwprintf 3 ,
497 and
498 .Xr vswprintf 3 ,
499 and wide character identifier of %lc, %C, %ls, %S for conventional
500 formatted I/O functions.
501 .El
502 .Sh SEE ALSO
503 .Xr gencat 1 ,
504 .Xr vidcontrol 1 ,
505 .Xr xfd 1 ,
506 .Xr xterm 1 ,
507 .Xr catgets 3 ,
508 .Xr gettext 3 Pq Pa pkgsrc/devel/gettext ,
509 .Xr nl_langinfo 3 ,
510 .Xr setlocale 3
511 .Sh BUGS
512 This man page is incomplete.