util/X86LINUX64/man/mann/msgcat.n

   1 '\"
   2 '\" Copyright (c) 1998 Mark Harrison.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH "msgcat" n 1.5 msgcat "Tcl Bundled Packages"
   8 .\" The -*- nroff -*- definitions below are for supplemental macros used
   9 .\" in Tcl/Tk manual entries.
  10 .\"
  11 .\" .AP type name in/out ?indent?
  12 .\"     Start paragraph describing an argument to a library procedure.
  13 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  14 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  15 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  16 .\"     needed;  use .AS below instead)
  17 .\"
  18 .\" .AS ?type? ?name?
  19 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  20 .\"     name are examples of largest possible arguments that will be passed
  21 .\"     to .AP later.  If args are omitted, default tab stops are used.
  22 .\"
  23 .\" .BS
  24 .\"     Start box enclosure.  From here until next .BE, everything will be
  25 .\"     enclosed in one large box.
  26 .\"
  27 .\" .BE
  28 .\"     End of box enclosure.
  29 .\"
  30 .\" .CS
  31 .\"     Begin code excerpt.
  32 .\"
  33 .\" .CE
  34 .\"     End code excerpt.
  35 .\"
  36 .\" .VS ?version? ?br?
  37 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  38 .\"     of man pages.  The first argument is ignored and used for recording
  39 .\"     the version when the .VS was added, so that the sidebars can be
  40 .\"     found and removed when they reach a certain age.  If another argument
  41 .\"     is present, then a line break is forced before starting the sidebar.
  42 .\"
  43 .\" .VE
  44 .\"     End of vertical sidebar.
  45 .\"
  46 .\" .DS
  47 .\"     Begin an indented unfilled display.
  48 .\"
  49 .\" .DE
  50 .\"     End of indented unfilled display.
  51 .\"
  52 .\" .SO ?manpage?
  53 .\"     Start of list of standard options for a Tk widget. The manpage
  54 .\"     argument defines where to look up the standard options; if
  55 .\"     omitted, defaults to "options". The options follow on successive
  56 .\"     lines, in three columns separated by tabs.
  57 .\"
  58 .\" .SE
  59 .\"     End of list of standard options for a Tk widget.
  60 .\"
  61 .\" .OP cmdName dbName dbClass
  62 .\"     Start of description of a specific option.  cmdName gives the
  63 .\"     option's name as specified in the class command, dbName gives
  64 .\"     the option's name in the option database, and dbClass gives
  65 .\"     the option's class in the option database.
  66 .\"
  67 .\" .UL arg1 arg2
  68 .\"     Print arg1 underlined, then print arg2 normally.
  69 .\"
  70 .\" .QW arg1 ?arg2?
  71 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  72 .\"
  73 .\" .PQ arg1 ?arg2?
  74 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  75 .\"     (for trailing punctuation) and then a closing parenthesis.
  76 .\"
  77 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  78 .if t .wh -1.3i ^B
  79 .nr ^l \n(.l
  80 .ad b
  81 .\"     # Start an argument description
  82 .de AP
  83 .ie !"\\$4"" .TP \\$4
  84 .el \{\
  85 .   ie !"\\$2"" .TP \\n()Cu
  86 .   el          .TP 15
  87 .\}
  88 .ta \\n()Au \\n()Bu
  89 .ie !"\\$3"" \{\
  90 \&\\$1 \\fI\\$2\\fP (\\$3)
  91 .\".b
  92 .\}
  93 .el \{\
  94 .br
  95 .ie !"\\$2"" \{\
  96 \&\\$1  \\fI\\$2\\fP
  97 .\}
  98 .el \{\
  99 \&\\fI\\$1\\fP
 100 .\}
 101 .\}
 102 ..
 103 .\"     # define tabbing values for .AP
 104 .de AS
 105 .nr )A 10n
 106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 107 .nr )B \\n()Au+15n
 108 .\"
 109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 111 ..
 112 .AS Tcl_Interp Tcl_CreateInterp in/out
 113 .\"     # BS - start boxed text
 114 .\"     # ^y = starting y location
 115 .\"     # ^b = 1
 116 .de BS
 117 .br
 118 .mk ^y
 119 .nr ^b 1u
 120 .if n .nf
 121 .if n .ti 0
 122 .if n \l'\\n(.lu\(ul'
 123 .if n .fi
 124 ..
 125 .\"     # BE - end boxed text (draw box now)
 126 .de BE
 127 .nf
 128 .ti 0
 129 .mk ^t
 130 .ie n \l'\\n(^lu\(ul'
 131 .el \{\
 132 .\"     Draw four-sided box normally, but don't draw top of
 133 .\"     box if the box started on an earlier page.
 134 .ie !\\n(^b-1 \{\
 135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 136 .\}
 137 .el \}\
 138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 139 .\}
 140 .\}
 141 .fi
 142 .br
 143 .nr ^b 0
 144 ..
 145 .\"     # VS - start vertical sidebar
 146 .\"     # ^Y = starting y location
 147 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 148 .de VS
 149 .if !"\\$2"" .br
 150 .mk ^Y
 151 .ie n 'mc \s12\(br\s0
 152 .el .nr ^v 1u
 153 ..
 154 .\"     # VE - end of vertical sidebar
 155 .de VE
 156 .ie n 'mc
 157 .el \{\
 158 .ev 2
 159 .nf
 160 .ti 0
 161 .mk ^t
 162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 163 .sp -1
 164 .fi
 165 .ev
 166 .\}
 167 .nr ^v 0
 168 ..
 169 .\"     # Special macro to handle page bottom:  finish off current
 170 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 171 .\"     # page bottom macro.
 172 .de ^B
 173 .ev 2
 174 'ti 0
 175 'nf
 176 .mk ^t
 177 .if \\n(^b \{\
 178 .\"     Draw three-sided box if this is the box's first page,
 179 .\"     draw two sides but no top otherwise.
 180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 182 .\}
 183 .if \\n(^v \{\
 184 .nr ^x \\n(^tu+1v-\\n(^Yu
 185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 186 .\}
 187 .bp
 188 'fi
 189 .ev
 190 .if \\n(^b \{\
 191 .mk ^y
 192 .nr ^b 2
 193 .\}
 194 .if \\n(^v \{\
 195 .mk ^Y
 196 .\}
 197 ..
 198 .\"     # DS - begin display
 199 .de DS
 200 .RS
 201 .nf
 202 .sp
 203 ..
 204 .\"     # DE - end display
 205 .de DE
 206 .fi
 207 .RE
 208 .sp
 209 ..
 210 .\"     # SO - start of list of standard options
 211 .de SO
 212 'ie '\\$1'' .ds So \\fBoptions\\fR
 213 'el .ds So \\fB\\$1\\fR
 214 .SH "STANDARD OPTIONS"
 215 .LP
 216 .nf
 217 .ta 5.5c 11c
 218 .ft B
 219 ..
 220 .\"     # SE - end of list of standard options
 221 .de SE
 222 .fi
 223 .ft R
 224 .LP
 225 See the \\*(So manual entry for details on the standard options.
 226 ..
 227 .\"     # OP - start of full description for a single option
 228 .de OP
 229 .LP
 230 .nf
 231 .ta 4c
 232 Command-Line Name:      \\fB\\$1\\fR
 233 Database Name:  \\fB\\$2\\fR
 234 Database Class: \\fB\\$3\\fR
 235 .fi
 236 .IP
 237 ..
 238 .\"     # CS - begin code excerpt
 239 .de CS
 240 .RS
 241 .nf
 242 .ta .25i .5i .75i 1i
 243 ..
 244 .\"     # CE - end code excerpt
 245 .de CE
 246 .fi
 247 .RE
 248 ..
 249 .\"     # UL - underline word
 250 .de UL
 251 \\$1\l'|0\(ul'\\$2
 252 ..
 253 .\"     # QW - apply quotation marks to word
 254 .de QW
 255 .ie '\\*(lq'"' ``\\$1''\\$2
 256 .\"" fix emacs highlighting
 257 .el \\*(lq\\$1\\*(rq\\$2
 258 ..
 259 .\"     # PQ - apply parens and quotation marks to word
 260 .de PQ
 261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 262 .\"" fix emacs highlighting
 263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 264 ..
 265 .\"     # QR - quoted range
 266 .de QR
 267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 268 .\"" fix emacs highlighting
 269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 270 ..
 271 .\"     # MT - "empty" string
 272 .de MT
 273 .QW ""
 274 ..
 275 .BS
 276 '\" Note:  do not modify the .SH NAME line immediately below!
 277 .SH NAME
 278 msgcat \- Tcl message catalog
 279 .SH SYNOPSIS
 280 \fBpackage require Tcl 8.5\fR
 281 .sp
 282 \fBpackage require msgcat 1.5\fR
 283 .sp
 284 \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR?
 285 .sp
 286 \fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR?
 287 .sp
 288 \fB::msgcat::mclocale \fR?\fInewLocale\fR?
 289 .sp
 290 \fB::msgcat::mcpreferences\fR
 291 .sp
 292 \fB::msgcat::mcload \fIdirname\fR
 293 .sp
 294 \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR?
 295 .sp
 296 \fB::msgcat::mcmset \fIlocale src-trans-list\fR
 297 .sp
 298 .VS "TIP 404"
 299 \fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR?
 300 .sp
 301 \fB::msgcat::mcflmset \fIsrc-trans-list\fR
 302 .VE "TIP 404"
 303 .sp
 304 \fB::msgcat::mcunknown \fIlocale src-string\fR ?\fIarg arg ...\fR?
 305 .BE
 306 .SH DESCRIPTION
 307 .PP
 308 The \fBmsgcat\fR package provides a set of functions
 309 that can be used to manage multi-lingual user interfaces.
 310 Text strings are defined in a
 311 .QW "message catalog"
 312 which is independent from the application, and
 313 which can be edited or localized without modifying
 314 the application source code.  New languages
 315 or locales are provided by adding a new file to
 316 the message catalog.
 317 .PP
 318 Use of the message catalog is optional by any application
 319 or package, but is encouraged if the application or package
 320 wishes to be enabled for multi-lingual applications.
 321 .SH COMMANDS
 322 .TP
 323 \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR?
 324 .
 325 Returns a translation of \fIsrc-string\fR according to the
 326 user's current locale.  If additional arguments past \fIsrc-string\fR
 327 are given, the \fBformat\fR command is used to substitute the
 328 additional arguments in the translation of \fIsrc-string\fR.
 329 .RS
 330 .PP
 331 \fB::msgcat::mc\fR will search the messages defined
 332 in the current namespace for a translation of \fIsrc-string\fR; if
 333 none is found, it will search in the parent of the current namespace,
 334 and so on until it reaches the global namespace.  If no translation
 335 string exists, \fB::msgcat::mcunknown\fR is called and the string
 336 returned from \fB::msgcat::mcunknown\fR is returned.
 337 .PP
 338 \fB::msgcat::mc\fR is the main function used to localize an
 339 application.  Instead of using an English string directly, an
 340 application can pass the English string through \fB::msgcat::mc\fR and
 341 use the result.  If an application is written for a single language in
 342 this fashion, then it is easy to add support for additional languages
 343 later simply by defining new message catalog entries.
 344 .RE
 345 .TP
 346 \fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR?
 347 .
 348 Given several source strings, \fB::msgcat::mcmax\fR returns the length
 349 of the longest translated string.  This is useful when designing
 350 localized GUIs, which may require that all buttons, for example, be a
 351 fixed width (which will be the width of the widest button).
 352 .TP
 353 \fB::msgcat::mclocale \fR?\fInewLocale\fR?
 354 .
 355 This function sets the locale to \fInewLocale\fR.  If \fInewLocale\fR
 356 is omitted, the current locale is returned, otherwise the current locale
 357 is set to \fInewLocale\fR.  msgcat stores and compares the locale in a
 358 case-insensitive manner, and returns locales in lowercase.
 359 The initial locale is determined by the locale specified in
 360 the user's environment.  See \fBLOCALE SPECIFICATION\fR
 361 below for a description of the locale string format.
 362 .TP
 363 \fB::msgcat::mcpreferences\fR
 364 .
 365 Returns an ordered list of the locales preferred by
 366 the user, based on the user's language specification.
 367 The list is ordered from most specific to least
 368 preference.  The list is derived from the current
 369 locale set in msgcat by \fB::msgcat::mclocale\fR, and
 370 cannot be set independently.  For example, if the
 371 current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR
 372 returns \fB{en_US_funky en_US en {}}\fR.
 373 .TP
 374 \fB::msgcat::mcload \fIdirname\fR
 375 .
 376 Searches the specified directory for files that match
 377 the language specifications returned by \fB::msgcat::mcpreferences\fR
 378 (note that these are all lowercase), extended by the file extension
 379 .QW .msg .
 380 Each matching file is
 381 read in order, assuming a UTF-8 encoding.  The file contents are
 382 then evaluated as a Tcl script.  This means that Unicode characters
 383 may be present in the message file either directly in their UTF-8
 384 encoded form, or by use of the backslash-u quoting recognized by Tcl
 385 evaluation.  The number of message files which matched the specification
 386 and were loaded is returned.
 387 .TP
 388 \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR?
 389 .
 390 Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR
 391 in the specified \fIlocale\fR and the current namespace.  If
 392 \fItranslate-string\fR is not specified, \fIsrc-string\fR is used
 393 for both.  The function returns \fItranslate-string\fR.
 394 .TP
 395 \fB::msgcat::mcmset \fIlocale src-trans-list\fR
 396 .
 397 Sets the translation for multiple source strings in
 398 \fIsrc-trans-list\fR in the specified \fIlocale\fR and the current
 399 namespace.
 400 \fIsrc-trans-list\fR must have an even number of elements and is in
 401 the form {\fIsrc-string translate-string\fR ?\fIsrc-string
 402 translate-string ...\fR?} \fB::msgcat::mcmset\fR can be significantly
 403 faster than multiple invocations of \fB::msgcat::mcset\fR. The function
 404 returns the number of translations set.
 405 .TP
 406 \fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR?
 407 .VS "TIP 404"
 408 Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR in the
 409 current namespace for the locale implied by the name of the message catalog
 410 being loaded via \fB::msgcat::mcload\fR.  If \fItranslate-string\fR is not
 411 specified, \fIsrc-string\fR is used for both.  The function returns
 412 \fItranslate-string\fR.
 413 .VE "TIP 404"
 414 .TP
 415 \fB::msgcat::mcflmset \fIsrc-trans-list\fR
 416 .VS "TIP 404"
 417 Sets the translation for multiple source strings in \fIsrc-trans-list\fR in
 418 the current namespace for the locale implied by the name of the message
 419 catalog being loaded via \fB::msgcat::mcload\fR. \fIsrc-trans-list\fR must
 420 have an even number of elements and is in the form {\fIsrc-string
 421 translate-string\fR ?\fIsrc-string translate-string ...\fR?}
 422 \fB::msgcat::mcflmset\fR can be significantly faster than multiple invocations
 423 of \fB::msgcat::mcflset\fR. The function returns the number of translations set.
 424 .VE "TIP 404"
 425 .TP
 426 \fB::msgcat::mcunknown \fIlocale src-string\fR ?\fIarg arg ...\fR?
 427 .
 428 This routine is called by \fB::msgcat::mc\fR in the case when
 429 a translation for \fIsrc-string\fR is not defined in the
 430 current locale.  The default action is to return
 431 \fIsrc-string\fR passed by format if there are any arguments.  This
 432 procedure can be redefined by the
 433 application, for example to log error messages for each unknown
 434 string.  The \fB::msgcat::mcunknown\fR procedure is invoked at the
 435 same stack context as the call to \fB::msgcat::mc\fR.  The return value
 436 of \fB::msgcat::mcunknown\fR is used as the return value for the call
 437 to \fB::msgcat::mc\fR.
 438 .SH "LOCALE SPECIFICATION"
 439 .PP
 440 The locale is specified to \fBmsgcat\fR by a locale string
 441 passed to \fB::msgcat::mclocale\fR.
 442 The locale string consists of
 443 a language code, an optional country code, and an optional
 444 system-specific code, each separated by
 445 .QW _ .
 446 The country and language
 447 codes are specified in standards ISO-639 and ISO-3166.
 448 For example, the locale
 449 .QW en
 450 specifies English and
 451 .QW en_US
 452 specifies U.S. English.
 453 .PP
 454 When the msgcat package is first loaded, the locale is initialized
 455 according to the user's environment.  The variables \fBenv(LC_ALL)\fR,
 456 \fBenv(LC_MESSAGES)\fR, and \fBenv(LANG)\fR are examined in order.
 457 The first of them to have a non-empty value is used to determine the
 458 initial locale.  The value is parsed according to the XPG4 pattern
 459 .PP
 460 .CS
 461 language[_country][.codeset][@modifier]
 462 .CE
 463 .PP
 464 to extract its parts.  The initial locale is then set by calling
 465 \fB::msgcat::mclocale\fR with the argument
 466 .PP
 467 .CS
 468 language[_country][_modifier]
 469 .CE
 470 .PP
 471 On Windows and Cygwin, if none of those environment variables is set,
 472 msgcat will attempt to extract locale information from the registry.
 473 From Windows Vista on, the RFC4747 locale name "lang-script-country-options"
 474 is transformed to the locale as "lang_country_script" (Example:
 475 sr-Latn-CS -> sr_cs_latin). For Windows XP, the language id is
 476 transformed analoguously (Example: 0c1a -> sr_yu_cyrillic).
 477 If all these attempts to discover an initial locale from the user's
 478 environment fail, msgcat defaults to an initial locale of
 479 .QW C .
 480 .PP
 481 When a locale is specified by the user, a
 482 .QW "best match"
 483 search is performed during string translation.  For example, if a user
 484 specifies
 485 en_GB_Funky, the locales
 486 .QW en_GB_Funky ,
 487 .QW en_GB ,
 488 .QW en
 489 and
 490 .MT
 491 (the empty string)
 492 are searched in order until a matching translation
 493 string is found.  If no translation string is available, then
 494 \fB::msgcat::mcunknown\fR is called.
 495 .SH "NAMESPACES AND MESSAGE CATALOGS"
 496 .PP
 497 Strings stored in the message catalog are stored relative
 498 to the namespace from which they were added.  This allows
 499 multiple packages to use the same strings without fear
 500 of collisions with other packages.  It also allows the
 501 source string to be shorter and less prone to typographical
 502 error.
 503 .PP
 504 For example, executing the code
 505 .PP
 506 .CS
 507 \fB::msgcat::mcset\fR en hello "hello from ::"
 508 namespace eval foo {
 509     \fB::msgcat::mcset\fR en hello "hello from ::foo"
 510 }
 511 puts [\fB::msgcat::mc\fR hello]
 512 namespace eval foo {puts [\fB::msgcat::mc\fR hello]}
 513 .CE
 514 .PP
 515 will print
 516 .PP
 517 .CS
 518 hello from ::
 519 hello from ::foo
 520 .CE
 521 .PP
 522 When searching for a translation of a message, the
 523 message catalog will search first the current namespace,
 524 then the parent of the current namespace, and so on until
 525 the global namespace is reached.  This allows child namespaces to
 526 .QW inherit
 527 messages from their parent namespace.
 528 .PP
 529 For example, executing (in the
 530 .QW en
 531 locale) the code
 532 .PP
 533 .CS
 534 \fB::msgcat::mcset\fR en m1 ":: message1"
 535 \fB::msgcat::mcset\fR en m2 ":: message2"
 536 \fB::msgcat::mcset\fR en m3 ":: message3"
 537 namespace eval ::foo {
 538     \fB::msgcat::mcset\fR en m2 "::foo message2"
 539     \fB::msgcat::mcset\fR en m3 "::foo message3"
 540 }
 541 namespace eval ::foo::bar {
 542     \fB::msgcat::mcset\fR en m3 "::foo::bar message3"
 543 }
 544 namespace import \fB::msgcat::mc\fR
 545 puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"
 546 namespace eval ::foo {puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"}
 547 namespace eval ::foo::bar {puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"}
 548 .CE
 549 .PP
 550 will print
 551 .PP
 552 .CS
 553 :: message1; :: message2; :: message3
 554 :: message1; ::foo message2; ::foo message3
 555 :: message1; ::foo message2; ::foo::bar message3
 556 .CE
 557 .SH "LOCATION AND FORMAT OF MESSAGE FILES"
 558 .PP
 559 Message files can be located in any directory, subject
 560 to the following conditions:
 561 .IP [1]
 562 All message files for a package are in the same directory.
 563 .IP [2]
 564 The message file name is a msgcat locale specifier (all lowercase) followed by
 565 .QW .msg .
 566 For example:
 567 .PP
 568 .CS
 569 es.msg    \(em spanish
 570 en_gb.msg \(em United Kingdom English
 571 .CE
 572 .PP
 573 \fIException:\fR The message file for the root locale
 574 .MT
 575 is called
 576 .QW \fBROOT.msg\fR .
 577 This exception is made so as not to
 578 cause peculiar behavior, such as marking the message file as
 579 .QW hidden
 580 on Unix file systems.
 581 .IP [3]
 582 The file contains a series of calls to \fBmcflset\fR and
 583 \fBmcflmset\fR, setting the necessary translation strings
 584 for the language, likely enclosed in a \fBnamespace eval\fR
 585 so that all source strings are tied to the namespace of
 586 the package. For example, a short \fBes.msg\fR might contain:
 587 .PP
 588 .CS
 589 namespace eval ::mypackage {
 590     \fB::msgcat::mcflset\fR "Free Beer!" "Cerveza Gracias!"
 591 }
 592 .CE
 593 .SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES"
 594 .PP
 595 If a package is installed into a subdirectory of the
 596 \fBtcl_pkgPath\fR and loaded via \fBpackage require\fR, the
 597 following procedure is recommended.
 598 .IP [1]
 599 During package installation, create a subdirectory
 600 \fBmsgs\fR under your package directory.
 601 .IP [2]
 602 Copy your *.msg files into that directory.
 603 .IP [3]
 604 Add the following command to your package initialization script:
 605 .PP
 606 .CS
 607 # load language files, stored in msgs subdirectory
 608 \fB::msgcat::mcload\fR [file join [file dirname [info script]] msgs]
 609 .CE
 610 .SH "POSITIONAL CODES FOR FORMAT AND SCAN COMMANDS"
 611 .PP
 612 It is possible that a message string used as an argument
 613 to \fBformat\fR might have positionally dependent parameters that
 614 might need to be repositioned.  For example, it might be
 615 syntactically desirable to rearrange the sentence structure
 616 while translating.
 617 .PP
 618 .CS
 619 format "We produced %d units in location %s" $num $city
 620 format "In location %s we produced %d units" $city $num
 621 .CE
 622 .PP
 623 This can be handled by using the positional
 624 parameters:
 625 .PP
 626 .CS
 627 format "We produced %1\e$d units in location %2\e$s" $num $city
 628 format "In location %2\e$s we produced %1\e$d units" $num $city
 629 .CE
 630 .PP
 631 Similarly, positional parameters can be used with \fBscan\fR to
 632 extract values from internationalized strings. Note that it is not
 633 necessary to pass the output of \fB::msgcat::mc\fR to \fBformat\fR
 634 directly; by passing the values to substitute in as arguments, the
 635 formatting substitution is done directly.
 636 .PP
 637 .CS
 638 \fBmsgcat::mc\fR {Produced %1$d at %2$s} $num $city
 639 # ... where that key is mapped to one of the
 640 # human-oriented versions by \fBmsgcat::mcset\fR
 641 .CE
 642 .SH CREDITS
 643 .PP
 644 The message catalog code was developed by Mark Harrison.
 645 .SH "SEE ALSO"
 646 format(n), scan(n), namespace(n), package(n)
 647 .SH KEYWORDS
 648 internationalization, i18n, localization, l10n, message, text, translation
 649 .\" Local Variables:
 650 .\" mode: nroff
 651 .\" End: