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.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.