1mNAME0m
       msgcat - Tcl message catalog

1mSYNOPSIS0m
       1m::msgcat::mc 4m22msrc-string0m

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

       1m::msgcat::mcpreferences0m

       1m::msgcat::mcload 4m22mdirname0m

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

       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::mcunknown  22mis  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 applicaton can pass the
       English string through 1m::msgcat::mc 22mand use the result.  If an applica-
       tion  is written for a single language in this fashion, then it is easy
       to add support for additional languages later simply  by  defining  new
       message catalog entries.

       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.  The initial locale defaults to the
              locale specified in the  user's  environment.   See  1mLOCALE  AND0m
              1mSUBLOCALE  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.  If the user has  speci-
              fied  LANG=en_US_funky, this procedure would return {en_US_funky
              en_US en}.

       1m::msgcat::mcload 4m22mdirname0m
              Searches the specified directory for files that match  the  lan-
              guage  specifications returned by 1m::msgcat::mcpreferences22m.  Each
              file located is sourced.  The file extension is  ``.msg''.   The
              number 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.   If  4mtranslate-string24m is not specified, 4msrc-0m
              4mstring24m is used for both.  The function returns 4mtranslate-string24m.

       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  vaue  of  1m::msgcat::mcunknown 22mis used as the return
              vaue for the call to 1m::msgcat::mc22m.


1mLOCALE AND SUBLOCALE SPECIFICATION0m
       The locale is specified by a locale string.  The locale string consists
       of  a  language code, an optional country code, and an optional system-
       specific code, each separated by ``_''.  The country and language codes
       are  specified  in  standards  ISO-639  and ISO-3166.  For example, the
       locale ``en'' specifies English and
        ``en_US'' specifes  U.S. English.

       The locale defaults to the value in 1menv(LANG) 22mat the  time  the  1mmsgcat0m
       package  is  loaded.   If  1menv(LANG)  22mis  not  defined, then the locale
       defaults to ``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_UK_Funky, the locales ``en_UK_Funky'',  ``en_UK'',  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
              mcset en hello "hello from ::"
              namespace eval foo {mcset en hello "hello from ::foo"}
              puts [mc hello]
              namespace eval foo {puts [mc hello]}
       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
       namespace.

       For example, executing the code
              mcset en m1 ":: message1"
              mcset en m2 ":: message2"
              mcset en m3 ":: message3"
              namespace eval ::foo {
                  mcset en m2 "::foo message2"
                  mcset en m3 "::foo message3"
              }
              namespace eval ::foo::bar {
                  mcset en m3 "::foo::bar message3"
              }
              puts "[mc m1]; [mc m2]; [mc m3]"
              namespace eval ::foo {puts "[mc m1]; [mc m2]; [mc m3]"}
              namespace eval ::foo::bar {puts "[mc m1]; [mc m2]; [mc m3]"}
       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  locale  specifier  followed  by
              ``.msg''.  For example:
              es.msg    -- spanish
              en_UK.msg -- UK English

       [3]    The file contains a series of calls to mcset, setting the neces-
              sary translation strings for the language. For example:
              ::msgcat::mcset es "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
              ::msgcat::mcload [file join [file dirname [info script]] msgs]


1mPOSTITIONAL 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
       values 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-
