diff options
Diffstat (limited to 'tcl/doc/msgcat.n')
| -rw-r--r-- | tcl/doc/msgcat.n | 119 |
1 files changed, 87 insertions, 32 deletions
diff --git a/tcl/doc/msgcat.n b/tcl/doc/msgcat.n index 37c2a76fcd5..1c11f174450 100644 --- a/tcl/doc/msgcat.n +++ b/tcl/doc/msgcat.n @@ -7,13 +7,19 @@ '\" SCCS: @(#) msgcat.n '\" .so man.macros -.TH "msgcat" n 8.1 Tcl "Tcl Built-In Commands" +.TH "msgcat" n 1.3 msgcat "Tcl Bundled Packages" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME msgcat \- Tcl message catalog .SH SYNOPSIS -\fB::msgcat::mc \fIsrc-string\fR +\fBpackage require Tcl 8.2\fR +.sp +\fBpackage require msgcat 1.3\fR +.sp +\fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR? +.sp +\fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR? .sp \fB::msgcat::mclocale \fR?\fInewLocale\fR? .sp @@ -23,6 +29,8 @@ msgcat \- Tcl message catalog .sp \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR? .sp +\fB::msgcat::mcmset \fIlocale src-trans-list\fR +.sp \fB::msgcat::mcunknown \fIlocale src-string\fR .BE @@ -58,38 +66,63 @@ returned from \fB::msgcat::mcunknown\fR is returned. .PP \fB::msgcat::mc\fR is the main function used to localize an application. Instead of using an English string directly, an -applicaton can pass the English string through \fB::msgcat::mc\fR and +application can pass the English string through \fB::msgcat::mc\fR 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. .TP +\fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR? +Given several source strings, \fB::msgcat::mcmax\fR 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). +.TP \fB::msgcat::mclocale \fR?\fInewLocale\fR? This function sets the locale to \fInewLocale\fR. If \fInewLocale\fR is omitted, the current locale is returned, otherwise the current locale -is set to \fInewLocale\fR. -The initial locale defaults to the locale specified in -the user's environment. See \fBLOCALE AND SUBLOCALE SPECIFICATION\fR +is set to \fInewLocale\fR. 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 \fBLOCALE SPECIFICATION\fR below for a description of the locale string format. .TP \fB::msgcat::mcpreferences\fR 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 specified LANG=en_US_funky, -this procedure would return {en_US_funky en_US en}. +preference. The list is derived from the current +locale set in msgcat by \fBmsgcat::mclocale\fR, and +cannot be set independently. For example, if the +current locale is en_US_funky, then \fBmsgcat::mcpreferences\fR +returns {en_US_funky en_US en}. .TP \fB::msgcat::mcload \fIdirname\fR Searches the specified directory for files that match -the language specifications returned by \fB::msgcat::mcpreferences\fR. -Each file located is sourced. The file extension is ``.msg''. -The number of message files which matched the specification +the language specifications returned by \fB::msgcat::mcpreferences\fR +(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 non-Latin 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. .TP \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR? Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR -in the specified \fIlocale\fR. If \fItranslate-string\fR is not -specified, \fIsrc-string\fR is used for both. The function -returns \fItranslate-string\fR. +in the specified \fIlocale\fR and the current namespace. If +\fItranslate-string\fR is not specified, \fIsrc-string\fR is used +for both. The function returns \fItranslate-string\fR. +.TP +\fB::msgcat::mcmset \fIlocale src-trans-list\fR +Sets the translation for multiple source strings in +\fIsrc-trans-list\fR in the specified \fIlocale\fR and the current +namespace. +\fIsrc-trans-list\fR must have an even number of elements and is in +the form {\fIsrc-string translate-string\fR ?\fIsrc-string +translate-string ...\fR?} \fBmsgcat::mcmset\fR can be significantly +faster than multiple invocations of \fBmsgcat::mcset\fR. The function +returns the number of translations set. .TP \fB::msgcat::mcunknown \fIlocale src-string\fR This routine is called by \fB::msgcat::mc\fR in the case when @@ -98,27 +131,43 @@ current locale. The default action is to return \fIsrc-string\fR. This procedure can be redefined by the application, for example to log error messages for each unknown string. The \fB::msgcat::mcunknown\fR procedure is invoked at the -same stack context as the call to \fB::msgcat::mc\fR. The return vaue -of \fB::msgcat::mcunknown\fR is used as the return vaue for the call +same stack context as the call to \fB::msgcat::mc\fR. The return value +of \fB::msgcat::mcunknown\fR is used as the return value for the call to \fB::msgcat::mc\fR. -.SH "LOCALE AND SUBLOCALE SPECIFICATION" +.SH "LOCALE SPECIFICATION" .PP -The locale is specified by a locale string. +The locale is specified to \fBmsgcat\fR by a locale string +passed to \fB::msgcat::mclocale\fR. 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. +For example, the locale ``en'' specifies English and ``en_US'' specifies +U.S. English. .PP -The locale defaults to the value in \fBenv(LANG)\fR at the time the -\fBmsgcat\fR package is loaded. If \fBenv(LANG)\fR is not defined, then the -locale defaults to ``C''. +When the msgcat package is first loaded, the locale is initialized +according to the user's environment. The variables \fBenv(LC_ALL)\fR, +\fBenv(LC_MESSAGES)\fR, and \fBenv(LANG)\fR 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 +.CS +language[_country][.codeset][@modifier] +.CE +to extract its parts. The initial locale is then set by calling +\fBmsgcat::mclocale\fR with the argument +.CS +language[_country][_modifier] +.CE +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''. .PP When a locale is specified by the user, a ``best match'' search is performed during string translation. For example, if a user specifies -en_UK_Funky, the locales ``en_UK_Funky'', ``en_UK'', and ``en'' are +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 \fB::msgcat::unknown\fR is called. @@ -151,7 +200,7 @@ 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. .PP -For example, executing the code +For example, executing (in the ``en'' locale) the code .CS mcset en m1 ":: message1" mcset en m2 ":: message2" @@ -181,17 +230,22 @@ to the following conditions: .IP [1] All message files for a package are in the same directory. .IP [2] -The message file name is a locale specifier followed -by ``.msg''. For example: +The message file name is a msgcat locale specifier (all lowercase) +followed by ``.msg''. For example: .CS es.msg -- spanish -en_UK.msg -- UK English +en_gb.msg -- United Kingdom English .CE .IP [3] -The file contains a series of calls to mcset, setting the -necessary translation strings for the language. For example: +The file contains a series of calls to \fBmcset\fR and +\fBmcmset\fR, setting the necessary translation strings +for the language, likely enclosed in a \fBnamespace eval\fR +so that all source strings are tied to the namespace of +the package. For example, a short \fBes.msg\fR might contain: .CS -::msgcat::mcset es "Free Beer!" "Cerveza Gracias!" +namespace eval ::mypackage { + ::msgcat::mcset es "Free Beer!" "Cerveza Gracias!" +} .CE .SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES" @@ -212,7 +266,7 @@ initialization script: ::msgcat::mcload [file join [file dirname [info script]] msgs] .CE -.SH "POSTITIONAL CODES FOR FORMAT AND SCAN COMMANDS" +.SH "POSITIONAL CODES FOR FORMAT AND SCAN COMMANDS" .PP It is possible that a message string used as an argument to \fBformat\fR might have positionally dependent parameters that @@ -240,5 +294,6 @@ The message catalog code was developed by Mark Harrison. .SH "SEE ALSO" format(n), scan(n), namespace(n), package(n) + .SH KEYWORDS internationalization, i18n, localization, l10n, message, text, translation |