distrib/share/tcl/help/tcl/intl/msgcat

   1 NAME
   2        msgcat - Tcl message catalog
   3
   4 SYNOPSIS
   5        package require Tcl 8.2
   6
   7        package require msgcat 1.3.4
   8
   9        ::msgcat::mc src-string ?arg arg ...?
  10
  11        ::msgcat::mcmax ?src-string src-string ...?
  12
  13        ::msgcat::mclocale ?newLocale?
  14
  15        ::msgcat::mcpreferences
  16
  17        ::msgcat::mcload dirname
  18
  19        ::msgcat::mcset locale src-string ?translate-string?
  20
  21        ::msgcat::mcmset locale src-trans-list
  22
  23        ::msgcat::mcunknown locale src-string
  24
  25
  26 DESCRIPTION
  27        The msgcat package provides a set of functions that can be used to man-
  28        age multi-lingual user interfaces.   Text  strings  are  defined  in  a
  29        ``message  catalog''  which  is  independent  from the application, and
  30        which can be edited or  localized  without  modifying  the  application
  31        source  code.   New  languages  or locales are provided by adding a new
  32        file to the message catalog.
  33
  34        Use of the message catalog is optional by any application  or  package,
  35        but  is  encouraged  if the application or package wishes to be enabled
  36        for multi-lingual applications.
  37
  38 COMMANDS
  39        ::msgcat::mc src-string ?arg arg ...?
  40               Returns a translation of src-string according to the user's cur-
  41               rent locale.  If additional arguments past src-string are given,
  42               the format command is used to substitute  the  additional  argu-
  43               ments in the translation of src-string.
  44
  45        ::msgcat::mc  will search the messages defined in the current namespace
  46        for a translation of src-string; if none is found, it  will  search  in
  47        the  parent  of  the  current namespace, and so on until it reaches the
  48        global namespace.  If no translation string exists, ::msgcat::mcunknown
  49        is called and the string returned from ::msgcat::mcunknown is returned.
  50
  51        ::msgcat::mc is the main function  used  to  localize  an  application.
  52        Instead  of  using  an English string directly, an application can pass
  53        the English string through ::msgcat::mc and  use  the  result.   If  an
  54        application  is  written for a single language in this fashion, then it
  55        is easy to add support for additional languages later simply by  defin-
  56        ing new message catalog entries.
  57
  58        ::msgcat::mcmax ?src-string src-string ...?
  59               Given several source strings, ::msgcat::mcmax returns the length
  60               of the longest translated string.  This is useful when designing
  61               localized GUIs, which may require that all buttons, for example,
  62               be a fixed width (which will be the width of the widest button).
  63
  64        ::msgcat::mclocale ?newLocale?
  65               This  function  sets  the  locale to newLocale.  If newLocale is
  66               omitted, the current locale is returned, otherwise  the  current
  67               locale  is  set  to  newLocale.   msgcat stores and compares the
  68               locale in a case-insensitive manner, and returns locales in low-
  69               ercase.   The  initial locale is determined by the locale speci-
  70               fied in the user's environment.  See LOCALE SPECIFICATION  below
  71               for a description of the locale string format.
  72
  73        ::msgcat::mcpreferences
  74               Returns  an  ordered  list of the locales preferred by the user,
  75               based on the user's language specification.  The list is ordered
  76               from  most  specific  to  least preference.  The list is derived
  77               from the current locale set in msgcat by ::msgcat::mclocale, and
  78               cannot be set independently.  For example, if the current locale
  79               is    en_US_funky,    then    ::msgcat::mcpreferences    returns
  80               {en_US_funky en_US en}.
  81
  82        ::msgcat::mcload dirname
  83               Searches  the  specified directory for files that match the lan-
  84               guage specifications returned by  ::msgcat::mcpreferences  (note
  85               that  these  are  all lowercase), extended by the file extension
  86               ``.msg''.  Each matching file is read in order, assuming a UTF-8
  87               encoding.  The file contents are then evaluated as a Tcl script.
  88               This means that Unicode characters may be present in the message
  89               file  either  directly in their UTF-8 encoded form, or by use of
  90               the backslash-u quoting recognized by Tcl evaluation.  The  num-
  91               ber  of  message  files which matched the specification and were
  92               loaded is returned.
  93
  94        ::msgcat::mcset locale src-string ?translate-string?
  95               Sets the translation for src-string to translate-string  in  the
  96               specified locale and the current namespace.  If translate-string
  97               is not specified, src-string is used  for  both.   The  function
  98               returns translate-string.
  99
 100        ::msgcat::mcmset locale src-trans-list
 101               Sets  the  translation for multiple source strings in src-trans-
 102               list in the specified locale and the  current  namespace.   src-
 103               trans-list  must  have  an even number of elements and is in the
 104               form {src-string translate-string  ?src-string  translate-string
 105               ...?} ::msgcat::mcmset can be significantly faster than multiple
 106               invocations of ::msgcat::mcset. The function returns the  number
 107               of translations set.
 108
 109        ::msgcat::mcunknown locale src-string
 110               This routine is called by ::msgcat::mc in the case when a trans-
 111               lation for src-string is not defined in the current locale.  The
 112               default  action  is to return src-string.  This procedure can be
 113               redefined by the application, for example to log error  messages
 114               for  each  unknown string.  The ::msgcat::mcunknown procedure is
 115               invoked at the same stack context as the call  to  ::msgcat::mc.
 116               The  return  value  of ::msgcat::mcunknown is used as the return
 117               value for the call to ::msgcat::mc.
 118
 119 LOCALE SPECIFICATION
 120        The locale is specified to msgcat by a locale string passed  to  ::msg-
 121        cat::mclocale.   The  locale  string  consists  of  a language code, an
 122        optional country code, and an optional system-specific code, each sepa-
 123        rated  by ``_''.  The country and language codes are specified in stan-
 124        dards ISO-639 and ISO-3166.  For example, the locale  ``en''  specifies
 125        English and ``en_US'' specifies U.S. English.
 126
 127        When  the  msgcat  package  is  first loaded, the locale is initialized
 128        according  to  the  user's  environment.   The  variables  env(LC_ALL),
 129        env(LC_MESSAGES),  and  env(LANG)  are examined in order.  The first of
 130        them to have a non-empty value is used to determine the initial locale.
 131        The value is parsed according to the XPG4 pattern
 132               language[_country][.codeset][@modifier]
 133        to extract its parts.  The initial locale is then set by calling ::msg-
 134        cat::mclocale with the argument
 135               language[_country][_modifier]
 136        On Windows, if none of those environment variables is set, msgcat  will
 137        attempt  to extract locale information from the registry.  If all these
 138        attempts to discover an initial  locale  from  the  user's  environment
 139        fail, msgcat defaults to an initial locale of ``C''.
 140
 141        When a locale is specified by the user, a ``best match'' search is per-
 142        formed during string translation.  For example,  if  a  user  specifies
 143        en_GB_Funky,  the  locales  ``en_GB_Funky'',  ``en_GB'', and ``en'' are
 144        searched in order until a matching translation string is found.  If  no
 145        translation string is available, then ::msgcat::mcunknown is called.
 146
 147 NAMESPACES AND MESSAGE CATALOGS
 148        Strings stored in the message catalog are stored relative to the names-
 149        pace from which they were added.  This allows multiple packages to  use
 150        the  same  strings  without fear of collisions with other packages.  It
 151        also allows the source string to be shorter and  less  prone  to  typo-
 152        graphical error.
 153
 154        For example, executing the code
 155               ::msgcat::mcset en hello "hello from ::"
 156               namespace eval foo {
 157                  ::msgcat::mcset en hello "hello from ::foo"
 158               }
 159               puts [::msgcat::mc hello]
 160               namespace eval foo {puts [::msgcat::mc hello]}
 161        will print
 162               hello from ::
 163               hello from ::foo
 164
 165        When searching for a translation of a message, the message catalog will
 166        search first the current namespace, then  the  parent  of  the  current
 167        namespace,  and  so  on  until  the  global namespace is reached.  This
 168        allows child namespaces to "inherit" messages from their parent  names-
 169        pace.
 170
 171        For example, executing (in the ``en'' locale) the code
 172               ::msgcat::mcset en m1 ":: message1"
 173               ::msgcat::mcset en m2 ":: message2"
 174               ::msgcat::mcset en m3 ":: message3"
 175               namespace eval ::foo {
 176                  ::msgcat::mcset en m2 "::foo message2"
 177                  ::msgcat::mcset en m3 "::foo message3"
 178               }
 179               namespace eval ::foo::bar {
 180                  ::msgcat::mcset en m3 "::foo::bar message3"
 181               }
 182               namespace import ::msgcat::mc
 183               puts "[mc m1]; [mc m2]; [mc m3]"
 184               namespace eval ::foo {puts "[mc m1]; [mc m2]; [mc m3]"}
 185               namespace eval ::foo::bar {puts "[mc m1]; [mc m2]; [mc m3]"}
 186        will print
 187               :: message1; :: message2; :: message3
 188               :: message1; ::foo message2; ::foo message3
 189               :: message1; ::foo message2; ::foo::bar message3
 190
 191 LOCATION AND FORMAT OF MESSAGE FILES
 192        Message files can be located in any directory, subject to the following
 193        conditions:
 194
 195        [1]    All message files for a package are in the same directory.
 196
 197        [2]    The message file name is a msgcat locale specifier  (all  lower-
 198               case) followed by ``.msg''.  For example:
 199               es.msg    -- spanish
 200               en_gb.msg -- United Kingdom English
 201
 202        [3]    The file contains a series of calls to mcset and mcmset, setting
 203               the necessary  translation  strings  for  the  language,  likely
 204               enclosed in a namespace eval so that all source strings are tied
 205               to the namespace of the package. For  example,  a  short  es.msg
 206               might contain:
 207               namespace eval ::mypackage {
 208                  ::msgcat::mcset es "Free Beer!" "Cerveza Gracias!"
 209               }
 210
 211 RECOMMENDED MESSAGE SETUP FOR PACKAGES
 212        If  a  package  is installed into a subdirectory of the tcl_pkgPath and
 213        loaded via package require, the following procedure is recommended.
 214
 215        [1]    During package installation, create a  subdirectory  msgs  under
 216               your package directory.
 217
 218        [2]    Copy your *.msg files into that directory.
 219
 220        [3]      Add  the  following  command  to  your  package initialization
 221               script:
 222               # load language files, stored in msgs subdirectory
 223               ::msgcat::mcload [file join [file dirname [info script]] msgs]
 224
 225 POSITIONAL CODES FOR FORMAT AND SCAN COMMANDS
 226        It is possible that a message string used  as  an  argument  to  format
 227        might  have  positionally  dependent  parameters  that might need to be
 228        repositioned.  For example, it  might  be  syntactically  desirable  to
 229        rearrange the sentence structure while translating.
 230               format "We produced %d units in location %s" $num $city
 231               format "In location %s we produced %d units" $city $num
 232
 233        This can be handled by using the positional parameters:
 234               format "We produced %1\$d units in location %2\$s" $num $city
 235               format "In location %2\$s we produced %1\$d units" $num $city
 236
 237        Similarly,  positional parameters can be used with scan to extract val-
 238        ues from internationalized strings.
 239
 240 CREDITS
 241        The message catalog code was developed by Mark Harrison.
 242
 243
 244 SEE ALSO
 245        format(n), scan(n), namespace(n), package(n)
 246
 247
 248 KEYWORDS
 249        internationalization, i18n, localization, l10n, message, text, transla-