share/man/man7/nls.7

   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.6 2008/01/26 15:14:41 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 .Pp
 144 .Bd -literal
 145         language[_territory][.codeset][@modifier]
 146 .Ed
 147 .Pp
 148 Valid values for the language field come from the ISO639 standard which
 149 defines two-character codes for many languages.
 150 Some common language codes are:
 151 .Pp
 152 .nf
 153 .ta \w'SERBO-CROATIAN'u+2n +\w'DE'u+5n +\w'OCEANIC/INDONESIAN'u+2nC
 154 \fILanguage Name\fP     \fICode\fP      \fILanguage Family\fP
 155 .ta \w'SERBO-CROATIAN'u+2n +\w'DE'u+5n +\w'OCEANIC/INDONESIAN'u+2nC
 156 .sp 5p
 157 ABKHAZIAN       AB      IBERO-CAUCASIAN
 158 AFAN (OROMO)    OM      HAMITIC
 159 AFAR    AA      HAMITIC
 160 AFRIKAANS       AF      GERMANIC
 161 ALBANIAN        SQ      INDO-EUROPEAN (OTHER)
 162 AMHARIC AM      SEMITIC
 163 ARABIC  AR      SEMITIC
 164 ARMENIAN        HY      INDO-EUROPEAN (OTHER)
 165 ASSAMESE        AS      INDIAN
 166 AYMARA  AY      AMERINDIAN
 167 AZERBAIJANI     AZ      TURKIC/ALTAIC
 168 BASHKIR BA      TURKIC/ALTAIC
 169 BASQUE  EU      BASQUE
 170 BENGALI BN      INDIAN
 171 BHUTANI DZ      ASIAN
 172 BIHARI  BH      INDIAN
 173 BISLAMA BI
 174 BRETON  BR      CELTIC
 175 BULGARIAN       BG      SLAVIC
 176 BURMESE MY      ASIAN
 177 BYELORUSSIAN    BE      SLAVIC
 178 CAMBODIAN       KM      ASIAN
 179 CATALAN CA      ROMANCE
 180 CHINESE ZH      ASIAN
 181 CORSICAN        CO      ROMANCE
 182 CROATIAN        HR      SLAVIC
 183 CZECH   CS      SLAVIC
 184 DANISH  DA      GERMANIC
 185 DUTCH   NL      GERMANIC
 186 ENGLISH EN      GERMANIC
 187 ESPERANTO       EO      INTERNATIONAL AUX.
 188 ESTONIAN        ET      FINNO-UGRIC
 189 FAROESE FO      GERMANIC
 190 FIJI    FJ      OCEANIC/INDONESIAN
 191 FINNISH FI      FINNO-UGRIC
 192 FRENCH  FR      ROMANCE
 193 FRISIAN FY      GERMANIC
 194 GALICIAN        GL      ROMANCE
 195 GEORGIAN        KA      IBERO-CAUCASIAN
 196 GERMAN  DE      GERMANIC
 197 GREEK   EL      LATIN/GREEK
 198 GREENLANDIC     KL      ESKIMO
 199 GUARANI GN      AMERINDIAN
 200 GUJARATI        GU      INDIAN
 201 HAUSA   HA      NEGRO-AFRICAN
 202 HEBREW  HE      SEMITIC
 203 HINDI   HI      INDIAN
 204 HUNGARIAN       HU      FINNO-UGRIC
 205 ICELANDIC       IS      GERMANIC
 206 INDONESIAN      ID      OCEANIC/INDONESIAN
 207 INTERLINGUA     IA      INTERNATIONAL AUX.
 208 INTERLINGUE     IE      INTERNATIONAL AUX.
 209 INUKTITUT       IU
 210 INUPIAK IK      ESKIMO
 211 IRISH   GA      CELTIC
 212 ITALIAN IT      ROMANCE
 213 JAPANESE        JA      ASIAN
 214 JAVANESE        JV      OCEANIC/INDONESIAN
 215 KANNADA KN      DRAVIDIAN
 216 KASHMIRI        KS      INDIAN
 217 KAZAKH  KK      TURKIC/ALTAIC
 218 KINYARWANDA     RW      NEGRO-AFRICAN
 219 KIRGHIZ KY      TURKIC/ALTAIC
 220 KURUNDI RN      NEGRO-AFRICAN
 221 KOREAN  KO      ASIAN
 222 KURDISH KU      IRANIAN
 223 LAOTHIAN        LO      ASIAN
 224 LATIN   LA      LATIN/GREEK
 225 LATVIAN LV      BALTIC
 226 LINGALA LN      NEGRO-AFRICAN
 227 LITHUANIAN      LT      BALTIC
 228 MACEDONIAN      MK      SLAVIC
 229 MALAGASY        MG      OCEANIC/INDONESIAN
 230 MALAY   MS      OCEANIC/INDONESIAN
 231 MALAYALAM       ML      DRAVIDIAN
 232 MALTESE MT      SEMITIC
 233 MAORI   MI      OCEANIC/INDONESIAN
 234 MARATHI MR      INDIAN
 235 MOLDAVIAN       MO      ROMANCE
 236 MONGOLIAN       MN
 237 NAURU   NA
 238 NEPALI  NE      INDIAN
 239 NORWEGIAN       NO      GERMANIC
 240 OCCITAN OC      ROMANCE
 241 ORIYA   OR      INDIAN
 242 PASHTO  PS      IRANIAN
 243 PERSIAN (farsi) FA      IRANIAN
 244 POLISH  PL      SLAVIC
 245 PORTUGUESE      PT      ROMANCE
 246 PUNJABI PA      INDIAN
 247 QUECHUA QU      AMERINDIAN
 248 RHAETO-ROMANCE  RM      ROMANCE
 249 ROMANIAN        RO      ROMANCE
 250 RUSSIAN RU      SLAVIC
 251 SAMOAN  SM      OCEANIC/INDONESIAN
 252 SANGHO  SG      NEGRO-AFRICAN
 253 SANSKRIT        SA      INDIAN
 254 SCOTS GAELIC    GD      CELTIC
 255 SERBIAN SR      SLAVIC
 256 SERBO-CROATIAN  SH      SLAVIC
 257 SESOTHO ST      NEGRO-AFRICAN
 258 SETSWANA        TN      NEGRO-AFRICAN
 259 SHONA   SN      NEGRO-AFRICAN
 260 SINDHI  SD      INDIAN
 261 SINGHALESE      SI      INDIAN
 262 SISWATI SS      NEGRO-AFRICAN
 263 SLOVAK  SK      SLAVIC
 264 SLOVENIAN       SL      SLAVIC
 265 SOMALI  SO      HAMITIC
 266 SPANISH ES      ROMANCE
 267 SUNDANESE       SU      OCEANIC/INDONESIAN
 268 SWAHILI SW      NEGRO-AFRICAN
 269 SWEDISH SV      GERMANIC
 270 TAGALOG TL      OCEANIC/INDONESIAN
 271 TAJIK   TG      IRANIAN
 272 TAMIL   TA      DRAVIDIAN
 273 TATAR   TT      TURKIC/ALTAIC
 274 TELUGU  TE      DRAVIDIAN
 275 THAI    TH      ASIAN
 276 TIBETAN BO      ASIAN
 277 TIGRINYA        TI      SEMITIC
 278 TONGA   TO      OCEANIC/INDONESIAN
 279 TSONGA  TS      NEGRO-AFRICAN
 280 TURKISH TR      TURKIC/ALTAIC
 281 TURKMEN TK      TURKIC/ALTAIC
 282 TWI     TW      NEGRO-AFRICAN
 283 UIGUR   UG
 284 UKRAINIAN       UK      SLAVIC
 285 URDU    UR      INDIAN
 286 UZBEK   UZ      TURKIC/ALTAIC
 287 VIETNAMESE      VI      ASIAN
 288 VOLAPUK VO      INTERNATIONAL AUX.
 289 WELSH   CY      CELTIC
 290 WOLOF   WO      NEGRO-AFRICAN
 291 XHOSA   XH      NEGRO-AFRICAN
 292 YIDDISH YI      GERMANIC
 293 YORUBA  YO      NEGRO-AFRICAN
 294 ZHUANG  ZA
 295 ZULU    ZU      NEGRO-AFRICAN
 296 .ta
 297 .fi
 298 .Pp
 299 For example, the locale for the Danish language spoken in Denmark
 300 using the ISO8859-1 character set is da_DK.ISO8859-1.
 301 The da stands for the Danish language and the DK stands for Denmark.
 302 The short form of da_DK is sufficient to indicate this locale.
 303 .Pp
 304 The environment variable settings are queried by their priority level
 305 in the following manner:
 306 .Pp
 307 .Bl -bullet
 308 .It
 309 If the
 310 .Ev LC_ALL
 311 environment variable is set, all six categories use the locale it
 312 specifies.
 313 .It
 314 If the
 315 .Ev LC_ALL
 316 environment variable is not set, each individual category uses the
 317 locale specified by its corresponding environment variable.
 318 .It
 319 If the
 320 .Ev LC_ALL
 321 environment variable is not set, and a value for a particular
 322 .Ev LC_*
 323 environment variable is not set, the value of the
 324 .Ev LANG
 325 environment variable specifies the default locale for all categories.
 326 Only the
 327 .Ev LANG
 328 environment variable should be set in /etc/profile, since it makes it
 329 most easy for the user to override the system default using the individual
 330 .Ev LC_*
 331 variables.
 332 .It
 333 If the
 334 .Ev LC_ALL
 335 environment variable is not set, a value for a particular
 336 .Ev LC_*
 337 environment variable is not set, and the value of the
 338 .Ev LANG
 339 environment variable is not set, the locale for that specific
 340 category defaults to the C locale.
 341 The C or POSIX locale assumes the 7-bit ASCII character set and defines
 342 information for the six categories.
 343 .El
 344 .Ss Character Sets
 345 A character is any symbol used for the organization, control, or
 346 representation of data.
 347 A group of such symbols used to describe a
 348 particular language make up a character set.
 349 It is the encoding values in a character set that provide
 350 the interface between the system and its input and output devices.
 351 .Pp
 352 The following character sets are supported in
 353 .Dx
 354 .Bl -tag -width ISO8859_family
 355 .It ISO8859 family
 356 Industry-standard character sets are provided by means of the ISO8859
 357 family of character sets, which provide a range of single-byte character set
 358 support that includes Latin-1, Latin-2, Arabic, Cyrillic, Hebrew,
 359 Greek, and Turkish.
 360 The eucJP character set is the industry-standard character set used to support
 361 the Japanese locale.
 362 .It Unicode
 363 A Unicode environment based on the UTF-8 character set is supported for all
 364 supported language/territories.
 365 UTF-8 provides character support for most of the major languages of the
 366 world and can be used in environments where multiple languages must be
 367 processed simultaneously.
 368 .El
 369 .Ss Font Sets
 370 A font set contains the glyphs to be displayed on the screen for a
 371 corresponding character in a character set.
 372 A display must support a suitable font to display a character set.
 373 If suitable fonts are available to the X server, then X clients can
 374 include support for different character sets.
 375 .Xr xterm 1
 376 includes support for UTF-8 character sets.
 377 .Xr xfd 1
 378 is useful for displaying all the characters in an X font.
 379 .Pp
 380 The
 381 .Dx
 382 .Xr syscons 4
 383 console provides support for loading a variety of fonts using the
 384 .Xr vidcontrol 1
 385 utility. Available fonts can be found in
 386 .Pa /usr/share/syscons/fonts .
 387 .Ss Internationalization for Programmers
 388 To facilitate translations of messages into various languages and to
 389 make the translated messages available to the program based on a
 390 user's locale, it is necessary to keep messages separate from the
 391 programs and provide them in the form of message catalogs that a
 392 program can access at run time.
 393 .Pp
 394 Access to locale information is provided through the
 395 .Xr setlocale 3
 396 and
 397 .Xr nl_langinfo 3
 398 interfaces.
 399 See their respective man pages for further information.
 400 .Pp
 401 Message source files containing application messages are created by
 402 the programmer and converted to message catalogs.
 403 These catalogs are used by the application to retrieve and display
 404 messages, as needed.
 405 .Pp
 406 .Dx
 407 supports two message catalog interfaces: the X/Open
 408 .Xr catgets 3
 409 interface and the Uniforum
 410 .Xr gettext 3
 411 interface.
 412 The
 413 .Xr catgets 3
 414 interface has the advantage that it belongs to a standard which is
 415 well supported.
 416 Unfortunately the interface is complicated to use and
 417 maintenance of the catalogs is difficult.
 418 The implementation also doesn't support different character sets.
 419 The
 420 .Xr gettext 3
 421 interface has not been standardized yet, however it is being supported
 422 by an increasing number of systems.
 423 It also provides many additional tools which make programming and
 424 catalog maintenance much easier.
 425 .Ss Support for Multibyte Characters and Wide Characters
 426 Character sets with multibyte characters may be difficult to decode, or may
 427 contain state (i.e., adjacent characters are dependent).
 428 ISO C specifies a set of functions using 'wide characters' which can handle
 429 multibyte characters properly.
 430 A wide character is specified in ISO C
 431 as being a fixed number of bits wide and is stateless.
 432 .Pp
 433 There are two types for wide characters:
 434 .Em wchar_t
 435 and
 436 .Em wint_t .
 437 .Em wchar_t
 438 is a type which can contain one wide character and operates like 'char'
 439 type does for one character.
 440 .Em wint_t
 441 can contain one wide character or WEOF (wide EOF).
 442 .Pp
 443 There are functions that operate on
 444 .Em wchar_t ,
 445 and substitute for functions operating on 'char'.
 446 See
 447 .Xr wmemchr 3
 448 and
 449 .Xr towlower 3
 450 for details.
 451 There are some additional functions that operate on
 452 .Em wchar_t .
 453 See
 454 .Xr wctype 3
 455 and
 456 .Xr wctrans 3
 457 for details.
 458 .Pp
 459 Wide characters should be used for all I/O processing which may rely
 460 on locale-specific strings.
 461 The two primary issues requiring special use of wide characters are:
 462 .Bl -bullet -offset indent
 463 .It
 464 All I/O is performed using multibyte characters.
 465 Input data is converted into wide characters immediately after
 466 reading and data for output is converted from wide characters to
 467 multibyte characters immediately before writing.
 468 Conversion is achieved using
 469 .Xr mbstowcs 3 ,
 470 .Xr mbsrtowcs 3 ,
 471 .Xr wcstombs 3 ,
 472 .Xr wcsrtombs 3 ,
 473 .Xr mblen 3 ,
 474 .Xr mbrlen 3 ,
 475 and
 476 .Xr  mbsinit 3 .
 477 .It
 478 Wide characters are used directly for I/O, using
 479 .Xr getwchar 3 ,
 480 .Xr fgetwc 3 ,
 481 .Xr getwc 3 ,
 482 .Xr ungetwc 3 ,
 483 .Xr fgetws 3 ,
 484 .Xr putwchar 3 ,
 485 .Xr fputwc 3 ,
 486 .Xr putwc 3 ,
 487 and
 488 .Xr fputws 3 .
 489 They are also used for formatted I/O functions for wide characters
 490 such as
 491 .Xr fwscanf 3 ,
 492 .Xr wscanf 3 ,
 493 .Xr swscanf 3 ,
 494 .Xr fwprintf 3 ,
 495 .Xr wprintf 3 ,
 496 .Xr swprintf 3 ,
 497 .Xr vfwprintf 3 ,
 498 .Xr vwprintf 3 ,
 499 and
 500 .Xr vswprintf 3 ,
 501 and wide character identifier of %lc, %C, %ls, %S for conventional
 502 formatted I/O functions.
 503 .El
 504 .Sh SEE ALSO
 505 .Xr gencat 1 ,
 506 .Xr vidcontrol 1 ,
 507 .Xr xfd 1 ,
 508 .Xr xterm 1 ,
 509 .Xr catgets 3 ,
 510 .Xr gettext 3 Pq Pa pkgsrc/devel/gettext ,
 511 .Xr nl_langinfo 3 ,
 512 .Xr setlocale 3
 513 .Sh BUGS
 514 This man page is incomplete.