tcl/doc/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 '\" SCCS: @(#) msgcat.n
   8 '\"
   9 .so man.macros
  10 .TH "msgcat" n 8.1 Tcl "Tcl Built-In Commands"
  11 .BS
  12 '\" Note:  do not modify the .SH NAME line immediately below!
  13 .SH NAME
  14 msgcat \- Tcl message catalog
  15 .SH SYNOPSIS
  16 \fB::msgcat::mc \fIsrc-string\fR
  17 .sp
  18 \fB::msgcat::mclocale \fR?\fInewLocale\fR?
  19 .sp
  20 \fB::msgcat::mcpreferences\fR
  21 .sp
  22 \fB::msgcat::mcload \fIdirname\fR
  23 .sp
  24 \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR?
  25 .sp
  26 \fB::msgcat::mcunknown \fIlocale src-string\fR
  27 .BE
  28
  29 .SH DESCRIPTION
  30 .PP
  31 The \fBmsgcat\fR package provides a set of functions
  32 that can be used to manage multi-lingual user interfaces.
  33 Text strings are defined in a ``message catalog'' which
  34 is independent from the application, and
  35 which can be edited or localized without modifying
  36 the application source code.  New languages
  37 or locales are provided by adding a new file to
  38 the message catalog.
  39 .PP
  40 Use of the message catalog is optional by any application
  41 or package, but is encouraged if the application or package
  42 wishes to be enabled for multi-lingual applications.
  43
  44 .SH COMMANDS
  45 .TP
  46 \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR?
  47 Returns a translation of \fIsrc-string\fR according to the
  48 user's current locale.  If additional arguments past \fIsrc-string\fR
  49 are given, the \fBformat\fR command is used to substitute the
  50 additional arguments in the translation of \fIsrc-string\fR.
  51
  52 \fB::msgcat::mc\fR will search the messages defined
  53 in the current namespace for a translation of \fIsrc-string\fR; if
  54 none is found, it will search in the parent of the current namespace,
  55 and so on until it reaches the global namespace.  If no translation
  56 string exists, \fB::msgcat::mcunknown\fR is called and the string
  57 returned from \fB::msgcat::mcunknown\fR is returned.
  58 .PP
  59 \fB::msgcat::mc\fR is the main function used to localize an
  60 application.  Instead of using an English string directly, an
  61 applicaton can pass the English string through \fB::msgcat::mc\fR and
  62 use the result.  If an application is written for a single language in
  63 this fashion, then it is easy to add support for additional languages
  64 later simply by defining new message catalog entries.
  65 .TP
  66 \fB::msgcat::mclocale \fR?\fInewLocale\fR?
  67 This function sets the locale to \fInewLocale\fR.  If \fInewLocale\fR
  68 is omitted, the current locale is returned, otherwise the current locale
  69 is set to \fInewLocale\fR.
  70 The initial locale defaults to the locale specified in
  71 the user's environment.  See \fBLOCALE AND SUBLOCALE SPECIFICATION\fR
  72 below for a description of the locale string format.
  73 .TP
  74 \fB::msgcat::mcpreferences\fR
  75 Returns an ordered list of the locales preferred by
  76 the user, based on the user's language specification.
  77 The list is ordered from most specific to least
  78 preference.  If the user has specified LANG=en_US_funky,
  79 this procedure would return {en_US_funky en_US en}.
  80 .TP
  81 \fB::msgcat::mcload \fIdirname\fR
  82 Searches the specified directory for files that match
  83 the language specifications returned by \fB::msgcat::mcpreferences\fR.
  84 Each file located is sourced.  The file extension is ``.msg''.
  85 The number of message files which matched the specification
  86 and were loaded is returned.
  87 .TP
  88 \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR?
  89 Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR
  90 in the specified \fIlocale\fR.  If \fItranslate-string\fR is not
  91 specified, \fIsrc-string\fR is used for both.  The function
  92 returns \fItranslate-string\fR.
  93 .TP
  94 \fB::msgcat::mcunknown \fIlocale src-string\fR
  95 This routine is called by \fB::msgcat::mc\fR in the case when
  96 a translation for \fIsrc-string\fR is not defined in the
  97 current locale.  The default action is to return
  98 \fIsrc-string\fR.  This procedure can be redefined by the
  99 application, for example to log error messages for each unknown
 100 string.  The \fB::msgcat::mcunknown\fR procedure is invoked at the
 101 same stack context as the call to \fB::msgcat::mc\fR.  The return vaue
 102 of \fB::msgcat::mcunknown\fR is used as the return vaue for the call
 103 to \fB::msgcat::mc\fR.
 104
 105 .SH "LOCALE AND SUBLOCALE SPECIFICATION"
 106 .PP
 107 The locale is specified by a locale string.
 108 The locale string consists of
 109 a language code, an optional country code, and an optional
 110 system-specific code, each separated by ``_''.  The country and language
 111 codes are specified in standards ISO-639 and ISO-3166.
 112 For example, the locale ``en'' specifies English and
 113  ``en_US'' specifes  U.S. English.
 114 .PP
 115 The locale defaults to the value in \fBenv(LANG)\fR at the time the
 116 \fBmsgcat\fR package is loaded.  If \fBenv(LANG)\fR is not defined, then the
 117 locale defaults to ``C''.
 118 .PP
 119 When a locale is specified by the user, a ``best match'' search is
 120 performed during string translation.  For example, if a user specifies
 121 en_UK_Funky, the locales ``en_UK_Funky'', ``en_UK'', and ``en'' are
 122 searched in order until a matching translation string is found.  If no
 123 translation string is available, then \fB::msgcat::unknown\fR is
 124 called.
 125
 126 .SH "NAMESPACES AND MESSAGE CATALOGS"
 127 .PP
 128 Strings stored in the message catalog are stored relative
 129 to the namespace from which they were added.  This allows
 130 multiple packages to use the same strings without fear
 131 of collisions with other packages.  It also allows the
 132 source string to be shorter and less prone to typographical
 133 error.
 134 .PP
 135 For example, executing the code
 136 .CS
 137 mcset en hello "hello from ::"
 138 namespace eval foo {mcset en hello "hello from ::foo"}
 139 puts [mc hello]
 140 namespace eval foo {puts [mc hello]}
 141 .CE
 142 will print
 143 .CS
 144 hello from ::
 145 hello from ::foo
 146 .CE
 147 .PP
 148 When searching for a translation of a message, the
 149 message catalog will search first the current namespace,
 150 then the parent of the current namespace, and so on until
 151 the global namespace is reached.  This allows child namespaces
 152 to "inherit" messages from their parent namespace.
 153 .PP
 154 For example, executing the code
 155 .CS
 156 mcset en m1 ":: message1"
 157 mcset en m2 ":: message2"
 158 mcset en m3 ":: message3"
 159 namespace eval ::foo {
 160     mcset en m2 "::foo message2"
 161     mcset en m3 "::foo message3"
 162 }
 163 namespace eval ::foo::bar {
 164     mcset en m3 "::foo::bar message3"
 165 }
 166 puts "[mc m1]; [mc m2]; [mc m3]"
 167 namespace eval ::foo {puts "[mc m1]; [mc m2]; [mc m3]"}
 168 namespace eval ::foo::bar {puts "[mc m1]; [mc m2]; [mc m3]"}
 169 .CE
 170 will print
 171 .CS
 172 :: message1; :: message2; :: message3
 173 :: message1; ::foo message2; ::foo message3
 174 :: message1; ::foo message2; ::foo::bar message3
 175 .CE
 176
 177 .SH "LOCATION AND FORMAT OF MESSAGE FILES"
 178 .PP
 179 Message files can be located in any directory, subject
 180 to the following conditions:
 181 .IP [1]
 182 All message files for a package are in the same directory.
 183 .IP [2]
 184 The message file name is a locale specifier followed
 185 by ``.msg''.  For example:
 186 .CS
 187 es.msg    -- spanish
 188 en_UK.msg -- UK English
 189 .CE
 190 .IP [3]
 191 The file contains a series of calls to mcset, setting the
 192 necessary translation strings for the language. For example:
 193 .CS
 194 ::msgcat::mcset es "Free Beer!" "Cerveza Gracias!"
 195 .CE
 196
 197 .SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES"
 198 .PP
 199 If a package is installed into a subdirectory of the
 200 \fBtcl_pkgPath\fR and loaded via \fBpackage require\fR, the
 201 following procedure is recommended.
 202 .IP [1]
 203 During package installation, create a subdirectory
 204 \fBmsgs\fR under your package directory.
 205 .IP [2]
 206 Copy your *.msg files into that directory.
 207 .IP [3]
 208  Add the following command to your package
 209 initialization script:
 210 .CS
 211 # load language files, stored in msgs subdirectory
 212 ::msgcat::mcload [file join [file dirname [info script]] msgs]
 213 .CE
 214
 215 .SH "POSTITIONAL CODES FOR FORMAT AND SCAN COMMANDS"
 216 .PP
 217 It is possible that a message string used as an argument
 218 to \fBformat\fR might have positionally dependent parameters that
 219 might need to be repositioned.  For example, it might be
 220 syntactically desirable to rearrange the sentence structure
 221 while translating.
 222 .CS
 223 format "We produced %d units in location %s" $num $city
 224 format "In location %s we produced %d units" $city $num
 225 .CE
 226 .PP
 227 This can be handled by using the positional
 228 parameters:
 229 .CS
 230 format "We produced %1\\$d units in location %2\\$s" $num $city
 231 format "In location %2\\$s we produced %1\\$d units" $num $city
 232 .CE
 233 .PP
 234 Similarly, positional parameters can be used with \fBscan\fR to
 235 extract values from internationalized strings.
 236
 237 .SH CREDITS
 238 .PP
 239 The message catalog code was developed by Mark Harrison.
 240
 241 .SH "SEE ALSO"
 242 format(n), scan(n), namespace(n), package(n)
 243 .SH KEYWORDS
 244 internationalization, i18n, localization, l10n, message, text, translation