1mNAME0m
       msgcat - Tcl message catalog

1mSYNOPSIS0m
       1mpackage require Tcl 8.20m

       1mpackage require msgcat 1.30m

       1m::msgcat::mc 4m22msrc-string24m ?4marg24m 4marg24m 4m...24m?

       1m::msgcat::mcmax ?4m22msrc-string24m 4msrc-string24m 4m...24m?

       1m::msgcat::mclocale 22m?4mnewLocale24m?

       1m::msgcat::mcpreferences0m

       1m::msgcat::mcload 4m22mdirname0m

       1m::msgcat::mcset 4m22mlocale24m 4msrc-string24m ?4mtranslate-string24m?

       1m::msgcat::mcmset 4m22mlocale24m 4msrc-trans-list0m

       1m::msgcat::mcunknown 4m22mlocale24m 4msrc-string0m


1mDESCRIPTION0m
       The 1mmsgcat 22mpackage provides a set of functions that can be used to man-
       age multi-lingual user interfaces.   Text  strings  are  defined  in  a
       ``message  catalog''  which  is  independent  from the application, and
       which can be edited or  localized  without  modifying  the  application
       source  code.   New  languages  or locales are provided by adding a new
       file to the message catalog.

       Use of the message catalog is optional by any application  or  package,
       but  is  encouraged  if the application or package wishes to be enabled
       for multi-lingual applications.

1mCOMMANDS0m
       1m::msgcat::mc 4m22msrc-string24m ?4marg24m 4marg24m 4m...24m?
              Returns a translation of 4msrc-string24m according to the user's cur-
              rent locale.  If additional arguments past 4msrc-string24m are given,
              the 1mformat 22mcommand is used to substitute  the  additional  argu-
              ments in the translation of 4msrc-string24m.

       1m::msgcat::mc  22mwill search the messages defined in the current namespace
       for a translation of 4msrc-string24m; if none is found, it  will  search  in
       the  parent  of  the  current namespace, and so on until it reaches the
       global namespace.  If no translation string exists, 1m::msgcat::mcunknown0m
       is called and the string returned from 1m::msgcat::mcunknown 22mis returned.

       1m::msgcat::mc 22mis the main function  used  to  localize  an  application.
       Instead  of  using  an English string directly, an application can pass
       the English string through 1m::msgcat::mc 22mand  use  the  result.   If  an
       application  is  written for a single language in this fashion, then it
       is easy to add support for additional languages later simply by  defin-
       ing new message catalog entries.

       1m::msgcat::mcmax ?4m22msrc-string24m 4msrc-string24m 4m...24m?
              Given several source strings, 1m::msgcat::mcmax 22mreturns the length
              of the longest translated string.  This is useful when designing
              localized GUIs, which may require that all buttons, for example,
              be a fixed width (which will be the width of the widest button).

       1m::msgcat::mclocale 22m?4mnewLocale24m?
              This  function  sets  the  locale to 4mnewLocale24m.  If 4mnewLocale24m is
              omitted, the current locale is returned, otherwise  the  current
              locale  is  set  to  4mnewLocale24m.   msgcat stores and compares the
              locale in a case-insensitive manner, and returns locales in low-
              ercase.   The  initial locale is determined by the locale speci-
              fied in the user's environment.  See 1mLOCALE SPECIFICATION  22mbelow
              for a description of the locale string format.

       1m::msgcat::mcpreferences0m
              Returns  an  ordered  list of the locales preferred by the user,
              based on the user's language specification.  The list is ordered
              from  most  specific  to  least preference.  The list is derived
              from the current locale set in msgcat by 1m::msgcat::mclocale22m, and
              cannot be set independently.  For example, if the current locale
              is    en_US_funky,    then    1m::msgcat::mcpreferences    22mreturns
              1m{en_US_funky en_US en}22m.

       1m::msgcat::mcload 4m22mdirname0m
              Searches  the  specified directory for files that match the lan-
              guage specifications returned by  1m::msgcat::mcpreferences  22m(note
              that  these  are  all lowercase), extended by the file extension
              ``.msg''.  Each matching file is read in order, assuming a UTF-8
              encoding.  The file contents are then evaluated as a Tcl script.
              This means that Unicode characters may be present in the message
              file  either  directly in their UTF-8 encoded form, or by use of
              the backslash-u quoting recognized by Tcl evaluation.  The  num-
              ber  of  message  files which matched the specification and were
              loaded is returned.

       1m::msgcat::mcset 4m22mlocale24m 4msrc-string24m ?4mtranslate-string24m?
              Sets the translation for 4msrc-string24m to 4mtranslate-string24m  in  the
              specified 4mlocale24m and the current namespace.  If 4mtranslate-string0m
              is not specified, 4msrc-string24m is used  for  both.   The  function
              returns 4mtranslate-string24m.

       1m::msgcat::mcmset 4m22mlocale24m 4msrc-trans-list0m
              Sets  the  translation for multiple source strings in 4msrc-trans-0m
              4mlist24m in the specified 4mlocale24m and the  current  namespace.   4msrc-0m
              4mtrans-list24m  must  have  an even number of elements and is in the
              form {4msrc-string24m 4mtranslate-string24m  ?4msrc-string24m  4mtranslate-string0m
              4m...24m?} 1m::msgcat::mcmset 22mcan be significantly faster than multiple
              invocations of 1m::msgcat::mcset22m. The function returns the  number
              of translations set.

       1m::msgcat::mcunknown 4m22mlocale24m 4msrc-string0m
              This routine is called by 1m::msgcat::mc 22min the case when a trans-
              lation for 4msrc-string24m is not defined in the current locale.  The
              default  action  is to return 4msrc-string24m.  This procedure can be
              redefined by the application, for example to log error  messages
              for  each  unknown string.  The 1m::msgcat::mcunknown 22mprocedure is
              invoked at the same stack context as the call  to  1m::msgcat::mc22m.
              The  return  value  of 1m::msgcat::mcunknown 22mis used as the return
              value for the call to 1m::msgcat::mc22m.

1mLOCALE SPECIFICATION0m
       The locale is specified to 1mmsgcat 22mby a locale string passed  to  1m::msg-0m
       1mcat::mclocale22m.   The  locale  string  consists  of  a language code, an
       optional country code, and an optional system-specific code, each sepa-
       rated  by ``_''.  The country and language codes are specified in stan-
       dards ISO-639 and ISO-3166.  For example, the locale  ``en''  specifies
       English and ``en_US'' specifies U.S. English.

       When  the  msgcat  package  is  first loaded, the locale is initialized
       according  to  the  user's  environment.   The  variables  1menv(LC_ALL)22m,
       1menv(LC_MESSAGES)22m,  and  1menv(LANG)  22mare examined in order.  The first of
       them to have a non-empty value is used to determine the initial locale.
       The value is parsed according to the XPG4 pattern
              language[_country][.codeset][@modifier]
       to extract its parts.  The initial locale is then set by calling 1m::msg-0m
       1mcat::mclocale 22mwith the argument
              language[_country][_modifier]
       On Windows, if none of those environment variables is set, msgcat  will
       attempt  to extract locale information from the registry.  If all these
       attempts to discover an initial  locale  from  the  user's  environment
       fail, msgcat defaults to an initial locale of ``C''.

       When a locale is specified by the user, a ``best match'' search is per-
       formed during string translation.  For example,  if  a  user  specifies
       en_GB_Funky,  the  locales  ``en_GB_Funky'',  ``en_GB'', and ``en'' are
       searched in order until a matching translation string is found.  If  no
       translation string is available, then 1m::msgcat::unknown 22mis called.

1mNAMESPACES AND MESSAGE CATALOGS0m
       Strings stored in the message catalog are stored relative to the names-
       pace from which they were added.  This allows multiple packages to  use
       the  same  strings  without fear of collisions with other packages.  It
       also allows the source string to be shorter and  less  prone  to  typo-
       graphical error.

       For example, executing the code
              1m::msgcat::mcset 22men hello "hello from ::"
              namespace eval foo {
                 1m::msgcat::mcset 22men hello "hello from ::foo"
              }
              puts [1m::msgcat::mc 22mhello]
              namespace eval foo {puts [1m::msgcat::mc 22mhello]}
       will print
              hello from ::
              hello from ::foo

       When searching for a translation of a message, the message catalog will
       search first the current namespace, then  the  parent  of  the  current
       namespace,  and  so  on  until  the  global namespace is reached.  This
       allows child namespaces to "inherit" messages from their parent  names-
       pace.

       For example, executing (in the ``en'' locale) the code
              1m::msgcat::mcset 22men m1 ":: message1"
              1m::msgcat::mcset 22men m2 ":: message2"
              1m::msgcat::mcset 22men m3 ":: message3"
              namespace eval ::foo {
                 1m::msgcat::mcset 22men m2 "::foo message2"
                 1m::msgcat::mcset 22men m3 "::foo message3"
              }
              namespace eval ::foo::bar {
                 1m::msgcat::mcset 22men m3 "::foo::bar message3"
              }
              namespace import 1m::msgcat::mc0m
              puts "[1mmc 22mm1]; [1mmc 22mm2]; [1mmc 22mm3]"
              namespace eval ::foo {puts "[1mmc 22mm1]; [1mmc 22mm2]; [1mmc 22mm3]"}
              namespace eval ::foo::bar {puts "[1mmc 22mm1]; [1mmc 22mm2]; [1mmc 22mm3]"}
       will print
              :: message1; :: message2; :: message3
              :: message1; ::foo message2; ::foo message3
              :: message1; ::foo message2; ::foo::bar message3

1mLOCATION AND FORMAT OF MESSAGE FILES0m
       Message files can be located in any directory, subject to the following
       conditions:

       [1]    All message files for a package are in the same directory.

       [2]    The message file name is a msgcat locale specifier  (all  lower-
              case) followed by ``.msg''.  For example:
              es.msg    -- spanish
              en_gb.msg -- United Kingdom English

       [3]    The file contains a series of calls to 1mmcset 22mand 1mmcmset22m, setting
              the necessary  translation  strings  for  the  language,  likely
              enclosed in a 1mnamespace eval 22mso that all source strings are tied
              to the namespace of the package. For  example,  a  short  1mes.msg0m
              might contain:
              namespace eval ::mypackage {
                 1m::msgcat::mcset 22mes "Free Beer!" "Cerveza Gracias!"
              }

1mRECOMMENDED MESSAGE SETUP FOR PACKAGES0m
       If  a  package  is installed into a subdirectory of the 1mtcl_pkgPath 22mand
       loaded via 1mpackage require22m, the following procedure is recommended.

       [1]    During package installation, create a  subdirectory  1mmsgs  22munder
              your package directory.

       [2]    Copy your *.msg files into that directory.

       [3]      Add  the  following  command  to  your  package initialization
              script:
              # load language files, stored in msgs subdirectory
              1m::msgcat::mcload 22m[file join [file dirname [info script]] msgs]

1mPOSITIONAL CODES FOR FORMAT AND SCAN COMMANDS0m
       It is possible that a message string used  as  an  argument  to  1mformat0m
       might  have  positionally  dependent  parameters  that might need to be
       repositioned.  For example, it  might  be  syntactically  desirable  to
       rearrange the sentence structure while translating.
              format "We produced %d units in location %s" $num $city
              format "In location %s we produced %d units" $city $num

       This can be handled by using the positional parameters:
              format "We produced %1\$d units in location %2\$s" $num $city
              format "In location %2\$s we produced %1\$d units" $num $city

       Similarly,  positional parameters can be used with 1mscan 22mto extract val-
       ues from internationalized strings.

1mCREDITS0m
       The message catalog code was developed by Mark Harrison.


1mSEE ALSO0m
       format(n), scan(n), namespace(n), package(n)


1mKEYWORDS0m
       internationalization, i18n, localization, l10n, message, text, transla-
