## Tcl9.0.3/Tk9.0.3 Documentation > Tcl Commands > msgcat

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  NAME
    msgcat — Tcl の伝達文目録 Tcl message catalog
  構文SYNOPSIS
  説明 DESCRIPTION
  諸命令 COMMANDS
    ::msgcat::mc src-string ?arg arg ...?
    ::msgcat::mcn namespace src-string ?arg arg ...?
    ::msgcat::mcmax ?src-string src-string ...?
    ::msgcat::mcexists ?-exactnamespace? ?-exactlocale? ?-namespace namespace? src-string
    ::msgcat::mcpackagenamespaceget
    ::msgcat::mclocale ?newLocale?
    ::msgcat::mcpreferences ?locale preference? ...
    ::msgcat::mcloadedlocales subcommand
    ::msgcat::mcload dirname
    ::msgcat::mcset locale src-string ?translate-string?
    ::msgcat::mcmset locale src-trans-list
    ::msgcat::mcflset src-string ?translate-string?
    ::msgcat::mcflmset src-trans-list
    ::msgcat::mcunknown locale src-string ?arg arg ...?
    ::msgcat::mcforgetpackage
    ::msgcat::mcutil getpreferences locale
    ::msgcat::mcutil getsystemlocale
  LOCALE SPECIFICATION
  名前空間と伝言文型録 NAMESPACES AND MESSAGE CATALOGS
  伝達文の位置と書式 LOCATION AND FORMAT OF MESSAGE FILES
  RECOMMENDED MESSAGE SETUP FOR PACKAGES
  POSITIONAL CODES FOR FORMAT AND SCAN COMMANDS
  PACKAGE PRIVATE LOCALE
    ::msgcat::mcpackagelocale set ?locale?
    ::msgcat::mcpackagelocale get
    ::msgcat::mcpackagelocale preferences ?locale preference? ...
    ::msgcat::mcpackagelocale loaded
    ::msgcat::mcpackagelocale isset
    ::msgcat::mcpackagelocale unset
    ::msgcat::mcpackagelocale present locale
    ::msgcat::mcpackagelocale clear
  梱包変更指示項目 CHANGING PACKAGE OPTIONS
    ::msgcat::mcpackageconfig get option
    ::msgcat::mcpackageconfig isset option
    ::msgcat::mcpackageconfig set option value
    ::msgcat::mcpackageconfig unset option
  梱包指示項目 Package options
    mcfolder
    loadcmd
    changecmd
    unknowncmd
  Callback invocation
  OBJECT ORIENTED PROGRAMMING
    1) In class definition script
    2) method defined in a class
    3) method defined in a classless object
  用例 EXAMPLES
  著作権表示 CREDITS
  SEE ALSO
  KEYWORDS

### NAME

msgcat — Tcl の伝達文目録 Tcl message catalog

### 構文SYNOPSIS

package require tcl 9.0
package require msgcat 1.7
::msgcat::mc src-string ?arg arg ...?
::msgcat::mcmax ?src-string src-string ...?
::msgcat::mcexists ?-exactnamespace? ?-exactlocale? src-string
::msgcat::mcpackagenamespaceget
::msgcat::mclocale ?newLocale?
::msgcat::mcpreferences ?locale preference? ...
::msgcat::mcloadedlocales subcommand
::msgcat::mcload dirname
::msgcat::mcset locale src-string ?translate-string?
::msgcat::mcmset locale src-trans-list
::msgcat::mcflset src-string ?translate-string?
::msgcat::mcflmset src-trans-list
::msgcat::mcunknown locale src-string ?arg arg ...?
::msgcat::mcpackagelocale subcommand ?locale?
::msgcat::mcpackageconfig subcommand option ?value?
::msgcat::mcforgetpackage
::msgcat::mcutil subcommand ?locale?

### 説明 DESCRIPTION

この msgcat 梱包は多言語の使用者との対話機能を管理する為に使用できる機能を揃えて提供する｡ 文章文字列は “伝達文目録”の中で定義されており､応用譜とは独立であって､応用譜の源譜を修正することなく､校正や方言化できる｡新しい言語や､地域情報は､伝達文目録に新しいファイルを追加することによりもたらされる｡ The msgcat package provides a set of functions that can be used to manage 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 may be provided by adding a new file to the message catalog.

msgcat はその名前空間により梱包を識別している｡それぞれの梱包は msgcat の中に自己の伝達文目録と構成設定の設定を有している｡ msgcat distinguishes packages by its namespace. Each package has its own message catalog and configuration settings in msgcat.

地域情報 locale は､スイス系ドイツ語に対する de_ch の様に､使用者の言葉を記述する詳細の文字列である｡msgcat 内には､現在のOSの地域情報により初期化された大域地域情報がある｡それぞれの梱包は大域地域情報を使用するか梱包固有の地域情報を使用するかを決めてもよい｡[訳註 de_ch は Deutsch(ドイツ語) Confederation Helvetica (スイス国の正式名称)由来の略号] A locale is a specification string describing a user language like de_ch for Swiss German. In msgcat, there is a global locale initialized by the system locale of the current system. Each package may decide to use the global locale or to use a package specific locale.

大域的地域情報は､譬えば使用者が主導したり､web中央集中処理装置のような多数使用者応用譜内部による言語の変更のような､なにかの要求により変化するかも知れない｡ The global locale may be changed on demand, for example by a user initiated language change or within a multi user application like a web server.

対象志向の算譜は梱包名前空間の使用に対応している｡ Object oriented programming is supported by the use of a package namespace.

### 諸命令 COMMANDS

::msgcat::mc src-string ?arg arg ...?
  現在の地域情報に従って src-string の翻訳を返す｡もし､ src-string の後ろに追加の引数が与えられると､ src-string の翻訳の中の､追加の引数を置換する為に format 命令が使用される｡ Returns a translation of src-string according to the current locale. If additional arguments past src-string are given, the format command is used to substitute the additional arguments in the translation of src-string.

  ::msgcat::mc は､ src-string の翻訳の為に､現在の名前空間の中に定義された伝達文を捜す; もし何も発見されないと､現在の名前空間の親の中を捜し､それを､大域名前空間に至る迄繰り返す｡もし翻訳文が存在しないと､::msgcat::mcunknown が呼ばれ､ ::msgcat::mcunknown から返った文字列が返される｡ ::msgcat::mc will search the messages defined in the current namespace for a translation of src-string; 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, ::msgcat::mcunknown is called and the string returned from ::msgcat::mcunknown is returned.

  ::msgcat::mc は､応用譜の地域化に使われる主機能である｡英語の文字列を直接使う代りに､応用譜は英語の文字列を ::msgcat::mc を通して渡すことができ､結果を使う｡もし､応用譜が単一の言語用にこの方式で書かれると､後になって､新しい伝達文目録の表題を定義するだけで､追加の言語を容易に運用できる｡ ::msgcat::mc is the main function used to localize an application. Instead of using an English string directly, an application can pass the English string through ::msgcat::mc and 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 defining new message catalog entries.

::msgcat::mcn namespace src-string ?arg arg ...?
  ::msgcat::mcに似ているが､第一引数として､伝達文名前空間の指定を伴う｡ Like ::msgcat::mc, but with the message namespace specified as first argument.

  名前空間梱包が呼出者の名前空間ではなかった場合に関して､mcnが使われ得る｡用例は､下の命令::msgcat::mcpackagenamespacegetの説明に示される｡ mcn may be used for cases where the package namespace is not the namespace of the caller. An example is shown within the description of the command ::msgcat::mcpackagenamespaceget below.

::msgcat::mcmax ?src-string src-string ...?
  幾つかの源の文字列が与えられると::msgcat::mcmax は最長の翻訳文の長さを返す｡これは､地方化した GUIs(画像化使用者操作手段)の設計に便利である､譬えば､そこでは幅を決める為に､全ての釦が必要であるかもしれない(最大幅の釦の寸法とか)｡ Given several source strings, ::msgcat::mcmax returns 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).

::msgcat::mcexists ?-exactnamespace? ?-exactlocale? ?-namespace namespace? src-string
  もし与えられた src-string に翻訳があれば論理的真値を返す｡ Return true, if there is a translation for the given src-string.

  現在の名前空間のみを確認し､どの親の名前空間も確認しない為には､-exa The search may be limited by the option -exactnamespace to only check the current namespace and not any parent namespaces.

  第１の好みの地域情報のみを確認する為には追加指定 -exactlocale によって限定できる(譬えば､大域地域情報が使用されている場合 ::msgcat::mcpreferences によって最初の要素のみが返って来る)｡ It may also be limited by the option -exactlocale to only check the first prefered locale (e.g. first element returned by ::msgcat::mcpreferences if global locale is used).

  明確な梱包名前空間は指示項目 -namespace によって指定できる｡呼出者の名前空間はもし明示的に指定されていなければ使うことができる｡ An explicit package namespace may be specified by the option -namespace. The namespace of the caller is used if not explicitly specified.

::msgcat::mcpackagenamespaceget
  呼出者の梱包を返す｡この命令は OBJECT ORIENTED PROGRAMMING の節で記述した全ての場合を処理する｡ Return the package namespace of the caller. This command handles all cases described in section OBJECT ORIENTED PROGRAMMING.

  用途の実施例は tooltip 梱包であり､tooltip が示される毎に訳を更新する為に呼出者の名前空間梱包を保存する: Example usage is a tooltip package, which saves the caller package namespace to update the translation each time the tooltip is shown:

      proc ::tooltip::tooltip {widget message} {
          ...
          set messagenamespace [uplevel 1 {::msgcat::mcpackagenamespaceget}]
          ...
          bind $widget  [list ::tooltip::show $widget $messagenamespace $message]
      }

      proc ::tooltip::show {widget messagenamespace message} {
          ...
          set message [::msgcat::mcn $messagenamespace $message]
          ...
      }

::msgcat::mclocale ?newLocale?
  もし newLocale が省略されると､現在の地域情報が返される､省略されないと､現在の地域情報が newLocale に設定される｡ If newLocale is omitted, the current locale is returned, otherwise the current locale is set to newLocale.

  もし新しい地域情報がnewLocaleに設定されると､対応する優先順位が算出され設定される｡譬えば､現在の地域情報が en_US_funky の場合､::msgcat::mcpreferences は{en_us_funky en_us en {}} を返す｡ If the new locale is set to newLocale, the corresponding preferences are calculated and set. For example, if the current locale is en_US_funky, then ::msgcat::mcpreferences returns {en_us_funky en_us en {}}.

  同じ結果は ::msgcat::mcpreferences {*}[::msgcat::mcutil getpreferences newLocale] でも得られる｡ The same result may be achieved by ::msgcat::mcpreferences {*}[::msgcat::mcutil getpreferences newLocale].

  現在の地域情報は常に mcpreferences に返されるリストの最初の要素になる｡ The current locale is always the first element of the list returned by mcpreferences.

  msgcat は地域情報を大文字-小文字区別せず較べ､保存し､小文字で地域情報を返す｡初期の地域情報は使用者の環境ないで定められた地域情報によって定めれられる｡地域情報の文字列書式の記述については下記の LOCALE SPECIFICATION を参照されたい｡ msgcat stores and compares the locale in a case-insensitive manner, and returns locales in lowercase. The initial locale is determined by the locale specified in the user's environment. See LOCALE SPECIFICATION below for a description of the locale string format.

  もし地域情報が設定されると､地域情報の優先順位リストが評価される｡このリスト内の地域情報は､未だ積込まれてない場合､今や積込まれる｡(訳註:jet->yet) If the locale is set, the preference list of locales is evaluated. Locales in this list are loaded now, if not jet loaded.

::msgcat::mcpreferences ?locale preference? ...
  引数なしでは､使用者により好まれた地域情報の順序リストを返す｡リストは使用者に最も好まれたものから好まれなかったものに整列されている｡ Without arguments, returns an ordered list of the locales preferred by the user. The list is ordered from most specific to least preference.

  地域情報の優先順位の一揃いは地域情報の優先度のリストを設定する為に与えられてもよい｡現在の地域情報は､地域情報の優先度のリストの先頭の要素で､設定される｡ A set of locale preferences may be given to set the list of locale preferences. The current locale is also set, which is the first element of the locale preferences list.

  地域情報の優先順位は､未だ積込まれてない場合､今や積込まれる｡(訳註:jet->yet) Locale preferences are loaded now, if not jet loaded.

  用例の如く､使用者は英語や仏語文書を好むかもしれない｡これは次の様に構成設定できる: As an example, the user may prefer French or English text. This may be configured by:

      ::msgcat::mcpreferences fr en {}

::msgcat::mcloadedlocales subcommand
  この群の命令は､地域情報梱包を設定しない梱包の為に､積込まれた地域情報のリストを管理する｡ This group of commands manage the list of loaded locales for packages not setting a package locale.

  loaded 副命令は現在積込まれている地域情報のリストを返す｡ The subcommand loaded returns the list of currently loaded locales.

  clear 副命令は､現在の優先リスト内に無い全ての地域情報とそのデータを刷新する｡ 　　　　　 The subcommand clear removes all locales and their data, which are not in the current preference list.

::msgcat::mcload dirname
  指定されたディレクトリーから ::msgcat::mcloadedlocales loaded (又は､梱包地域情報が設定されている場合は､ msgcat::mcpackagelocale preferences )(註意すべきは､これは全て小文字)によって返された言語指定に合致し､ファイル拡張子 “.msg” が着くファイルを捜す｡合致したそれぞれのファイルは順に､UTF-8 文字体系が仮定されて､読まれる｡ファイルの内容はTcl 記述譜として評価される｡これは､直接的なUTF-8番号化形式､であっても､Tcl評価に認識される逆斜線-uの引用を使用する形式であっても､伝達ファイル中にユニコード文字があることを意味している｡指定に合致して積込まれた伝達ファイルの個数が返される｡ 　　　 Searches the specified directory for files that match the language specifications returned by ::msgcat::mcloadedlocales loaded (or msgcat::mcpackagelocale preferences if a package locale is set) (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 number of message files which matched the specification and were loaded is returned.

  更に､与えられたフォルダーは､ msgcat 梱包内の､地域情報変更によって要求される伝言型録ファイルを最終的に組込む為の mcfolder 追加指定構成設定に保存される｡ 　　　 In addition, the given folder is stored in the msgcat package configuration option mcfolder to eventually load message catalog files required by a locale change.

::msgcat::mcset locale src-string ?translate-string?
  src-string から､指定した locale と現在の名前空間の translate-string に翻訳を設定する｡もし translate-string が指定されないと､両方とも src-string が使用される｡この函数は translate-string を返す｡ Sets the translation for src-string to translate-string in the specified locale and the current namespace. If translate-string is not specified, src-string is used for both. The function returns translate-string.

::msgcat::mcmset locale src-trans-list
  指定された locale と現在の名前空間の中の src-trans-list 中の､多数の源文字列のための翻訳を設定する｡ src-trans-list は偶数個の要素を含まねばならず､又 {src-string translate-string ?src-string translate-string ...?} の形式でなければならない｡ ::msgcat::mcmset は､::msgcat::mcset の多数回起動より断然速い｡この函数は､翻訳の個数が返される｡ Sets the translation for multiple source strings in src-trans-list in the specified locale and the current namespace. src-trans-list must have an even number of elements and is in the form {src-string translate-string ?src-string translate-string ...?} ::msgcat::mcmset can be significantly faster than multiple invocations of ::msgcat::mcset. The function returns the number of translations set.

::msgcat::mcflset src-string ?translate-string?
  現在の名前空間内の src-string についての translate-string への翻訳を ::msgcat::mcload 経由で積込んだ伝言型録の名前によって暗示された地域情報に設定する｡もし translate-string が指定されていない場合､src-string は両方に使用される｡この函数は translate-string を返す｡ Sets the translation for src-string to translate-string in the current namespace for the locale implied by the name of the message catalog being loaded via ::msgcat::mcload. If translate-string is not specified, src-string is used for both. The function returns translate-string.

::msgcat::mcflmset src-trans-list
  現在の名前空間内の src-trans-list 内の多数の源の文字列の翻訳を ::msgcat::mcload 経由で積込んだ伝言型録の名前によって暗示された地域情報に設定する｡ src-trans-list は偶数個の要素を有さねばならず､又､形式 {src-string translate-string ?src-string translate-string ...?} ::msgcat::mcflmset は ::msgcat::mcflset の複数回起動よりも本質的に高速になりうる｡この函数は翻訳の組の数を返す｡ Sets the translation for multiple source strings in src-trans-list in the current namespace for the locale implied by the name of the message catalog being loaded via ::msgcat::mcload. src-trans-list must have an even number of elements and is in the form {src-string translate-string ?src-string translate-string ...?} ::msgcat::mcflmset can be significantly faster than multiple invocations of ::msgcat::mcflset. The function returns the number of translations set.

::msgcat::mcunknown locale src-string ?arg arg ...?
  この函数は､src-string の翻訳が現在の地域情報に指定されていない場合に::msgcat::mc により呼出される｡無為設定の行動は､何であれ引数がある場合は書式化された src-string を返すことである｡この手続函数は応用譜で再定義可能であり､譬えば､それぞれの未知の文字列に不具合伝達文を日誌に記す等｡この ::msgcat::mcunknown 手続函数は ::msgcat::mc の呼出としての同じ棚の文脈で起動される｡::msgcat::mcunknown の返り値は::msgcat::mcR の呼び出しのための返り値として使用される｡ This routine is called by ::msgcat::mc in the case when a translation for src-string is not defined in the current locale. The default action is to return src-string passed by format if there are any arguments. This procedure can be redefined by the application, for example to log error messages for each unknown string. The ::msgcat::mcunknown procedure is invoked at the same stack context as the call to ::msgcat::mc. The return value of ::msgcat::mcunknown is used as the return value for the call to ::msgcat::mc.

  この業務は､関連梱包が梱包地域情報を未知の命令名に設定しない場合にのみこの業務が呼出されることに註意すべきである｡ Note that this routine is only called if the concerned package did not set a package locale unknown command name.

::msgcat::mcforgetpackage
  呼ばれた梱包は､全ての設定や翻訳も含めて､msgcat 梱包内部の､その全ての状態を刷新する｡ The calling package clears all its state within the msgcat package including all settings and translations.

::msgcat::mcutil getpreferences locale
  LOCALE SPECIFICATION の節の記述に従って与えらえた地域情報の優先順位リストを返す｡用例はスイス系独語とスイス系仏語の結合としての双母語領域 "Biel/Bienne" について優先順位の構築である｡ Return the preferences list of the given locale as described in the section LOCALE SPECIFICATION. An example is the composition of a preference list for the bilingual region "Biel/Bienne" as a concatenation of swiss german and swiss french:

      % concat [lrange [msgcat::mcutil getpreferences fr_CH] 0 end-1] [msgcat::mcutil getpreferences de_CH]
      fr_ch fr de_ch de {}

::msgcat::mcutil getsystemlocale
  体系の地域情報は LOCALE SPECIFICATION の節に記述によって返される｡ The system locale is returned as described by the section LOCALE SPECIFICATION.

### LOCALE SPECIFICATION

地域情報の文字列を ::msgcat::mclocale に渡すことにより､地域情報は､ msgcat を規定する｡この地域情報の文字列は言語番号､任意附加の国別番号､任意附加のOS指定番号､から構成され､それぞれは “_” で隔てられている｡国別と言語番号は ISO-639 と ISO-3166 規格に規定されている｡譬えば､地域情報 “en” は英語を指定し､ “en_US” は米国式英語を指定する｡ The locale is specified to msgcat by a locale string passed to ::msgcat::mclocale. 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” specifies U.S. English.

msgcat が始めて積込まれた時､地域情報は､使用者の環境に従って初期化される｡変数 env(LC_ALL) と env(LC_MESSAGES) と env(LANG) がこの順に調べられる｡その内の､非空の値を有する最初のものが初期の地域情報を定める｡その値は XPG4 模様に従って調査される When the msgcat package is first loaded, the locale is initialized according to the user's environment. The variables env(LC_ALL), env(LC_MESSAGES), and env(LANG) are 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]

その部品を抽出する為に｡最初の地域情報は次の引数を伴って､ ::msgcat::mclocale を呼出して設定される｡ to extract its parts. The initial locale is then set by calling ::msgcat::mclocale with the argument

    language[_country][_modifier]

Windows 上と Cygwin では､環境変数が設定されていないと msgcat はレジストリーから地域情報の情報を抽出しようとする｡ RFC4747 地域情報名称 "lang-script-country-options" は "lang_country_script" として地域情報に翻訳される(例: sr-Latn-CS -> sr_cs_latin)｡ もし､使用者の環境から初期の地域情報を発見しようとするこれらの試みが失敗すると､ msgcat は無為設定として初期の地域情報を “C” に設定する｡ On Windows and Cygwin, if none of those environment variables is set, msgcat will attempt to extract locale information from the registry. The RFC4747 locale name "lang-script-country-options" is transformed to the locale as "lang_country_script" (Example: sr-Latn-CS -> sr_cs_latin). If all these attempts to discover an initial locale from the user's environment fail, msgcat defaults to an initial locale of “C”.

地域情報が使用者に指定されると､文字列の翻訳の間､ “最善合致” 式捜索が遂行される｡譬えば､もし使用者がen_GB_Funky を指定すると､地域情報の “en_gb_funky” と “en_gb” と “en” と “” (空文字列)が､合致する翻訳文字列が見付る迄､順番に捜索される｡もし､利用できる翻訳文字列がないと､未知の操作子が呼出される｡ When a locale is specified by the user, a “best match” search is performed during string translation. For example, if a user specifies en_GB_Funky, the locales “en_gb_funky”, “en_gb”, “en” and “” (the empty string) are searched in order until a matching translation string is found. If no translation string is available, then the unknown handler is called.

### 名前空間と伝言文型録 NAMESPACES AND MESSAGE CATALOGS

伝達文目録に保存された文字列はそれが追加された名前空間から相対的位置に保存される｡これにより､他の梱包との衝突を起こさずに､多数の梱包に同じ文字列の使用を許容する｡又､源の文字列が短くなることを許容し､打鍵の誤りを減らす傾向がある｡ Strings stored in the message catalog are stored relative to the namespace 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 typographical error.

譬えば､この符号命令を実行すると For example, executing the code

    ::msgcat::mcset en hello "hello from ::"
    namespace eval foo {
        ::msgcat::mcset en hello "hello from ::foo"
    }
    puts [::msgcat::mc hello]
    namespace eval foo {puts [::msgcat::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.

譬えば､この譜を実行する( “en” の地域情報の中で) For example, executing (in the “en” locale) the code

    ::msgcat::mcset en m1 ":: message1"
    ::msgcat::mcset en m2 ":: message2"
    ::msgcat::mcset en m3 ":: message3"
    namespace eval ::foo {
        ::msgcat::mcset en m2 "::foo message2"
        ::msgcat::mcset en m3 "::foo message3"
    }
    namespace eval ::foo::bar {
        ::msgcat::mcset en m3 "::foo::bar message3"
    }
    namespace import ::msgcat::mc
    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

### 伝達文の位置と書式 LOCATION AND FORMAT OF MESSAGE FILES

次の条件に従えば､伝達文はどこのディレクトリーに置いてもよい｡ 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. 伝達文ファイル名は msgcat 地域情報規定子(全て小文字)に “.msg” を添えたものである｡譬えば: The message file name is a msgcat locale specifier (all lowercase) followed by “.msg”. For example:

    es.msg    — spanish
    en_gb.msg — United Kingdom English

例外: 根本位置 “” の地域情報伝達文ファイルは “ROOT.msg” と呼ばれる｡ この例外は､Unixファイル系の上で伝達文ファイルに “hidden(隠蔽)” の如き印を附す様な奇妙な振舞いを避ける様に作られた｡ Exception: The message file for the root locale “” is called “ROOT.msg”. This exception is made so as not to cause peculiar behavior, such as marking the message file as “hidden” on Unix file systems.

1. ファイルは mcflset と mcflmset の連続呼出を含んで､言語の為の必要な翻訳文字列を設定し､好ましくは､全ての源の文字列が梱包の名前空間に束縛される様に namespace eval の中に括られている｡譬えば､短い es.msg は之を含むことになる: 　　　　 The file contains a series of calls to mcflset and mcflmset, setting the necessary translation strings for the language, likely enclosed in a namespace eval so that all source strings are tied to the namespace of the package. For example, a short es.msg might contain:

    namespace eval ::mypackage {
        ::msgcat::mcflset "Free Beer" "Cerveza Gratis"
    }

### RECOMMENDED MESSAGE SETUP FOR PACKAGES

もし､梱包が tcl_pkgPath の子供のディレクトリーに実装され､ package require 経由で積込まれた場合､次の手順が推奨される｡ If a package is installed into a subdirectory of the tcl_pkgPath and loaded via package require, the following procedure is recommended.

1. 梱包を実装する間に､梱包のディレクトリーの下に子供のディレクトリー msgs を作る｡ During package installation, create a subdirectory msgs under your package directory.

2. 貴方の *.msg ファイルをそのディレクトリーに複写する｡ Copy your *.msg files into that directory.

3. 次の命令を､貴方の梱包の初期化記述譜に追加する: Add the following command to your package initialization script:

    # 言語ファイルを積込み､ msgs 子ディレクトリー内に保存した
    # load language files, stored in msgs subdirectory
    ::msgcat::mcload [file join [file dirname [info script]] msgs]

### POSITIONAL CODES FOR FORMAT AND SCAN COMMANDS

format への引数として使用した伝達文文字列は､位置に依存する假引数を有するかも知れず､それは､再配置を要するかもしれない｡譬えば､翻訳している間に文の構造を再配列することが構文上望ましいかもしれない｡ It is possible that a message string used as an argument to format 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

同様に位置による假引数は国際化した文字列から値を抽出する為に scan と供に使用されることも可能である｡註意すべきは､ format ディレクトリーへの ::msgcat::mcR の出力を渡す必要はない; 引数として代入する為の値を渡す為に書式置換が直接済まされる｡ Similarly, positional parameters can be used with scan to extract values from internationalized strings. Note that it is not necessary to pass the output of ::msgcat::mc to format directly; by passing the values to substitute in as arguments, the formatting substitution is done directly.

    msgcat::mc {Produced %1$d at %2$s} $num $city
    # …ここで､その鍵盤が msgcat::mcset による人に易しい
    # 版の内の一つに対応付けされた# ... where that key is mapped to one of the
    # human-oriented versions by msgcat::mcset

### PACKAGE PRIVATE LOCALE

msgcat を使用する梱包は､自己の私的地域情報梱包や､ ::msgcat::mclocale による大域的地域情報に依存しない自己用の積込まれた地域情報の揃い､の使用を選択できる｡ A package using msgcat may choose to use its own package private locale and its own set of loaded locales, independent to the global locale set by ::msgcat::mclocale.

これにより､どれかの地域情報の組込みや､他の梱包の削除にもよらず､又､大域的地域情報の変更の呼び戻し(下記参照)によらずに､梱包の変更ができる｡ This allows a package to change its locale without causing any locales load or removal in other packages and not to invoke the global locale change callback (see below).

この動作は､次の組合せで制御される: This action is controled by the following ensemble:

::msgcat::mcpackagelocale set ?locale?
  私的地域情報梱包を設定又は変更する｡ もし locale が与えられている場合､地域情報梱包は与えられた locale に設定される｡もし追加指定の locale が与えられない場合､この梱包は私的地域情報梱包様式に設定されるが､どの地域情報も変更されない(譬えば､もし梱包の前に大域地域情報が有効な場合､それは私的地域情報梱包に複写される)｡ Set or change a package private locale. The package private locale is set to the given locale if the locale is given. If the option locale is not given, the package is set to package private locale mode, but no locale is changed (e.g. if the global locale was valid for the package before, it is copied to the package private locale).

  本命令は､私的地域情報の積込みを惹き起こすかもしれない｡ This command may cause the load of locales.

::msgcat::mcpackagelocale get
  私的地域情報梱包を返すが､私的地域情報梱包が設定されていない場合は､大域的私的地域情報を返す｡ Return the package private locale or the global locale, if no package private locale is set.

::msgcat::mcpackagelocale preferences ?locale preference? ...
  假引数なしでは､私的優先順位の梱包を返すが､私的優先順位の梱包がない場合は､大域優先順位が設定される｡地域情報状態の梱包はは辺呼応されない( ::msgcat::mcpackagelocale set の逆)｡ With no parameters, return the package private preferences or the global preferences, if no package private locale is set. The package locale state (set or not) is not changed (in contrast to the command ::msgcat::mcpackagelocale set).

  もし地域情報の優先順位の揃いが与えられると､地域情報の優先順位の梱包として設定される｡地域情報の梱包は優先順位の第一要素に設定される｡もしかなり以前に設定されたものでない場合､地域情報の梱包が活性になる｡ If a set of locale preferences is given, it is set as package locale preference list. The package locale is set to the first element of the preference list. A package locale is activated, if it was not set so far.

  未だ積込まれてなかった場合､地域情報の優先順位が梱包として積込まれる｡ Locale preferences are loaded now for the package, if not yet loaded.

::msgcat::mcpackagelocale loaded
  この梱包の為に積込まれた地域情報のリストを返す｡ Return the list of locales loaded for this package.

::msgcat::mcpackagelocale isset
  私的地域情報梱包が設定されている場合､論理的真値を返す｡ Returns true, if a package private locale is set.

::msgcat::mcpackagelocale unset
  私的地域情報の設定を解除し､大域的地域情報を使用する｡ 地域情報を組込み､取り外して､梱包の為に組込まれた地域情報のリストを組込まれた大域地域情報リストに調整する｡　　　　 Unset the package private locale and use the global locale. Load and remove locales to adjust the list of loaded locales for the package to the global loaded locales list.

::msgcat::mcpackagelocale present locale
  与えられた地域情報が梱包の為の積込まれている場合に論理的真値を返す｡ Returns true, if the given locale is loaded for the package.

::msgcat::mcpackagelocale clear
  梱包優先にない､積込まれたどの梱包の地域情報も消去する｡ Clear any loaded locales of the package not present in the package preferences.

### 梱包変更指示項目 CHANGING PACKAGE OPTIONS

それぞれの msgcat を使用する梱包は msgcat の内部に追加指定の揃いを有する｡ 追加指定梱包は次の追加指定梱包の節で記述する｡ それぞれの追加指定梱包は次の組合せを使用して設定したり設定解消したりされる｡ Each package using msgcat has a set of options within msgcat. The package options are described in the next sectionPackage options. Each package option may be set or unset individually using the following ensemble:

::msgcat::mcpackageconfig get option
  与えられた指定項目 option の現在の値を返す｡この呼出しは､梱包の為にこの設定項目が設定されてい内場合は不都合を返す｡ Return the current value of the given option. This call returns an error if the option is not set for the package.

::msgcat::mcpackageconfig isset option
  与えられた設定項目 option がこの梱包の為に設定されている場合 1 を返し､そうでない場合は0を返す｡ Returns 1, if the given option is set for the package, 0 otherwise.

::msgcat::mcpackageconfig set option value
  与えられた設定項目 option に与えられた値 value を設定する｡ これは､設定項目 option に依存して追加の動作を惹き起こすかもしれない｡ 返り値は 0 又は､ mcfolder 追加指定の為に組込まれた梱包の数を返す｡ Set the given option to the given value. This may invoke additional actions in dependency of the option. The return value is 0 or the number of loaded packages for the option mcfolder.

::msgcat::mcpackageconfig unset option
  梱包の為の与えられた option の設定を取消す｡この梱包の為に option が設定されていない場合は何の動作もしない｡ Unsets the given option for the package. No action is taken if the option is not set for the package. The empty string is returned.

#### 梱包指示項目 Package options

次の梱包指示項目がそれぞれの梱包の為に使用できる: The following package options are available for each package:

mcfolder
  これは梱包の伝言文保存庫である｡この指示項目は mcload によって､又は副命令揃いによって設定される｡両者は等価であり､両者とも組込んだ伝言文型録ファイルの数を返す｡ This is the message folder of the package. This option is set by mcload and by the subcommand set. Both are identical and both return the number of loaded message catalog files.

  この値の設定又は変更は､梱包の為の優先順位に沿って含まれる全ての地域情報を組込むことになる｡これは､又､組込み命令揃いのどれでも起動を強制することになる(下記参照)｡ Setting or changing this value will load all locales contained in the preferences valid for the package. This implies also to invoke any set loadcmd (see below).

  この値の設定解消は､この梱包の為の伝言文ファイル積込みを不能にする｡ Unsetting this value will disable message file load for the package.

loadcmd
  この呼戻しは､この特性を設定させる梱包の為の伝言型録ファイルが組込まれる前に起動される｡ This callback is invoked before a set of message catalog files are loaded for the package which has this property set.

  この呼戻しは 伝言ファイル詰込みの為のどのような準備動作をする為や､基礎データの様な他の源資からの伝言データの取得の為に使用できる｡この場合､どの伝言ファイルも使用されない(mcfolderは設定解除)｡ This callback may be used to do any preparation work for message file load or to get the message data from another source like a data base. In this case, no message files are used (mcfolder is unset).

  下の callback invocation の節を見られたい｡この呼戻しに添えられる假引数リストは組込むべき地域情報のリストである｡ 　　　　　 See section callback invocation below. The parameter list appended to this callback is the list of locales to load.

  もしこの呼戻しが変更されると､梱包の為の優先順位に沿って呼出される｡ If this callback is changed, it is called with the preferences valid for the package.

changecmd
  この呼戻しは､省略時設定の地域情報の変更が遂行された時に起動される｡ その目的は､他言語による画像化使用者対話機能の表示の様な省略時設定の地域情報のどのような付随特性も更新することを許容する｡ This callback is invoked when a default local change was performed. Its purpose is to allow a package to update any dependency on the default locale like showing the GUI in another language.

  下の callback invocation の節を見られたい｡この呼戻しに添えられる假引数リストは mcpreferences である｡登録された呼戻しは特定の順序なしに起動される｡ See the callback invocation section below. The parameter list appended to this callback is mcpreferences. The registered callbacks are invoked in no particular order.

unknowncmd
  msgcat 梱包により供給された標準版の代りに､ mcunknown 手続函数の地域情報梱包を使用する(msgcat::mcunknown)｡ Use a package locale mcunknown procedure instead of the standard version supplied by the msgcat package (msgcat::mcunknown).

  呼出された手続函数は書式化された伝言文を返さねばならない､その文は最終的にmsgcat::mc によって返される｡ The called procedure must return the formatted message which will finally be returned by msgcat::mc.

  空文字列に設定する場合は､共通の未知処理子が使用される｡これは 引数が与えられない場合､返す時には鍵によって構成される｡ 引数が与えられた場合､引数を処理する為にformat命令が使用される｡ A generic unknown handler is used if set to the empty string. This consists of returning the key if no arguments are given. With given arguments, the format command is used to process the arguments.

  下の callback invocation の節を見られたい｡添えられる引数は msgcat::mcunknown に与えるものと同じである｡ See section callback invocation below. The appended arguments are identical to msgcat::mcunknown.

### Callback invocation

上述の通りに､梱包は一つ或は多数呼戻しを登録することを定めてよい｡ A package may decide to register one or multiple callbacks, as described above. PP 次の時に呼戻しが起動される: Callbacks are invoked, if:

1. 呼戻し命令が設定された｡ 　　　　　 1. the callback command is set,

2. その命令は空文字列ではない｡ 　　　　　 2. the command is not the empty string,

3. 登録する名前空間が実在する｡ 　　　　　 3. the registering namespace exists.

もし呼出した業務が不都合で失敗した場合､命令が完了した後､解釈実行機能の為の bgerror 業務が起動される｡ その不都合で失敗する為に､不都合が mc-命令の起動を惹き起こす場合のみ､例外は unknowncmd を呼出す｡ If a called routine fails with an error, the bgerror routine for the interpreter is invoked after command completion. Only exception is the callback unknowncmd, where an error causes the invoking mc-command to fail with that error.

### OBJECT ORIENTED PROGRAMMING

msgcat は対象志向の算譜によって実装された梱包を運営している｡対象と級は梱包の名前空間の内部で定義すべきである｡ msgcat supports packages implemented by object oriented programming. Objects and classes should be defined within a package namespace.

三つの運営されている状態があり､そこでは msgcat の命令(mc, mcexists, mcpackagelocale, mcforgetpackage, mcpackagenamespaceget, mcpackageconfig, mcset and mcmset)に対応する梱包名前空間は呼出され得る: There are 3 supported cases where package namespace sensitive commands of msgcat (mc, mcexists, mcpackagelocale, mcforgetpackage, mcpackagenamespaceget, mcpackageconfig, mcset and mcmset) may be called:

1) In class definition script
  msgcat 命令は級定義記述譜内部で呼出される｡ msgcat command is called within a class definition script.

      namespace eval ::N2 {
          mcload $dir/msgs
          oo::class create C1 {puts [mc Hi!]}
      }

2) method defined in a class
  msgcat 命令は対象の中の手段から呼ばれ､手段は級内で定義される｡ msgcat command is called from a method in an object and the method is defined in a class.

      namespace eval ::N3Class {
          mcload $dir/msgs
          oo::class create C1
          oo::define C1 method m1 {
              puts [mc Hi!]
          }
      }

3) method defined in a classless object
  msgcat は級無しの対象の手段から呼出される｡ msgcat command is called from a method of a classless object.

      namespace eval ::N4 {
          mcload $dir/msgs
          oo::object create O1
          oo::objdefine O1 method m1 {} {
              puts [mc Hi!]
          }
      }

### 用例 EXAMPLES

画像化使用者対話機能を表示する梱包は､大域的地域情報が変化した時その部品を更新する｡呼戻しを登録するために､これを使用する: Packages which display a GUI may update their widgets when the global locale changes. To register to a callback, use:

    namespace eval gui {
        msgcat::mcpackageconfig changecmd updateGUI

        proc updateGUI args {
            puts "New locale is '[lindex $args 0]'."
        }
    }
    % msgcat::mclocale fr
    fr
    % New locale is 'fr'.

もし地域情報(又は追加の地域情報)が基礎データの様な他の源資に含まれている場合､梱包は､ mcload ではなく積込み呼出を使用しても好い: If locales (or additional locales) are contained in another source like a database, a package may use the load callback and not mcload:

    namespace eval db {
        msgcat::mcpackageconfig loadcmd loadMessages

        proc loadMessages args {
            foreach locale $args {
                if {[LocaleInDB $locale]} {
                    msgcat::mcmset $locale [GetLocaleList $locale]
                }
            }
        }
    }

clock 命令の実装は､命令行假引数 -locale を実装する為の地域情報梱包を伴う msgcat 使用する｡これは実装の輪郭の一部である: 　　　 The clock command implementation uses msgcat with a package locale to implement the command line parameter -locale. Here are some sketches of the implementation:

最初に､地域情報梱包が初期化され､共通未知機能が不能化される: First, a package locale is initialized and the generic unknown function is deactivated:

    msgcat::mcpackagelocale set
    msgcat::mcpackageconfig unknowncmd ""

用例として､使用者が次の様に特定の地域情報内の曜日を要求する: As an example, the user requires the week day in a certain locale as follows:

    clock format [clock seconds] -format %A -locale fr

clock は地域情報梱包を fr に設定し､曜日を次の様に捜す: clock sets the package locale to fr and looks for the day name as follows:

    msgcat::mcpackagelocale set $locale
    return [lindex [msgcat::mc DAYS_OF_WEEK_FULL] $day]
    ###  "水曜日(仏語)" を返す;
    ### Returns "mercredi"

clock 内部で､ある伝言文型録項目は計算処理には重く､従って動的高速処理領域を使用する: Within clock, some message-catalog items are heavy in computation and thus are dynamically cached using:

    proc ::tcl::clock::LocalizeFormat { locale format } {
        set key FORMAT_$format
        if { [::msgcat::mcexists -exactlocale -exactnamespace $key] } {
            return [mc $key]
        }
        #...重い書式計算は摘まむ...
        #...expensive computation of format clipped...
        mcset $locale $key $format
        return $format
    }

### 著作権表示 CREDITS

伝達文目録の命令符号は Mark Harrison によって開発された｡ The message catalog code was developed by Mark Harrison.

### SEE ALSO

format, scan, namespace, package, oo::class, oo::object

### KEYWORDS

internationalization, i18n, localization, l10n, message, text, translation, class, object
Copyright © 1998 Mark Harrison.