diff options
Diffstat (limited to 'doc/msgcat.n')
| -rw-r--r-- | doc/msgcat.n | 385 |
1 files changed, 385 insertions, 0 deletions
diff --git a/doc/msgcat.n b/doc/msgcat.n new file mode 100644 index 0000000..bae6dbe --- /dev/null +++ b/doc/msgcat.n @@ -0,0 +1,385 @@ +'\" +'\" Copyright (c) 1998 Mark Harrison. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH "msgcat" n 1.5 msgcat "Tcl Bundled Packages" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +msgcat \- Tcl message catalog +.SH SYNOPSIS +\fBpackage require Tcl 8.5\fR +.sp +\fBpackage require msgcat 1.5\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 +\fB::msgcat::mcpreferences\fR +.sp +\fB::msgcat::mcload \fIdirname\fR +.sp +\fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR? +.sp +\fB::msgcat::mcmset \fIlocale src-trans-list\fR +.sp +.VS "TIP 404" +\fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR? +.sp +\fB::msgcat::mcflmset \fIsrc-trans-list\fR +.VE "TIP 404" +.sp +\fB::msgcat::mcunknown \fIlocale src-string\fR ?\fIarg arg ...\fR? +.BE +.SH DESCRIPTION +.PP +The \fBmsgcat\fR package provides a set of functions +that can be used to manage multi-lingual user interfaces. +Text strings are defined in a +.QW "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. +.PP +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. +.SH COMMANDS +.TP +\fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR? +. +Returns a translation of \fIsrc-string\fR according to the +user's current locale. If additional arguments past \fIsrc-string\fR +are given, the \fBformat\fR command is used to substitute the +additional arguments in the translation of \fIsrc-string\fR. +.RS +.PP +\fB::msgcat::mc\fR will search the messages defined +in the current namespace for a translation of \fIsrc-string\fR; 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, \fB::msgcat::mcunknown\fR is called and the string +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 +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. +.RE +.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. 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. The list is derived from the current +locale set in msgcat by \fB::msgcat::mclocale\fR, and +cannot be set independently. For example, if the +current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR +returns \fB{en_US_funky en_US en {}}\fR. +.TP +\fB::msgcat::mcload \fIdirname\fR +. +Searches the specified directory for files that match +the language specifications returned by \fB::msgcat::mcpreferences\fR +(note that these are all lowercase), extended by the file extension +.QW .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. +.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 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?} \fB::msgcat::mcmset\fR can be significantly +faster than multiple invocations of \fB::msgcat::mcset\fR. The function +returns the number of translations set. +.TP +\fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR? +.VS "TIP 404" +Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR in the +current namespace for the locale implied by the name of the message catalog +being loaded via \fB::msgcat::mcload\fR. If \fItranslate-string\fR is not +specified, \fIsrc-string\fR is used for both. The function returns +\fItranslate-string\fR. +.VE "TIP 404" +.TP +\fB::msgcat::mcflmset \fIsrc-trans-list\fR +.VS "TIP 404" +Sets the translation for multiple source strings in \fIsrc-trans-list\fR in +the current namespace for the locale implied by the name of the message +catalog being loaded via \fB::msgcat::mcload\fR. \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?} +\fB::msgcat::mcflmset\fR can be significantly faster than multiple invocations +of \fB::msgcat::mcflset\fR. The function returns the number of translations set. +.VE "TIP 404" +.TP +\fB::msgcat::mcunknown \fIlocale src-string\fR ?\fIarg arg ...\fR? +. +This routine is called by \fB::msgcat::mc\fR in the case when +a translation for \fIsrc-string\fR is not defined in the +current locale. The default action is to return +\fIsrc-string\fR 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 \fB::msgcat::mcunknown\fR procedure is invoked at the +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 SPECIFICATION" +.PP +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 +.QW _ . +The country and language +codes are specified in standards ISO-639 and ISO-3166. +For example, the locale +.QW en +specifies English and +.QW en_US +specifies U.S. English. +.PP +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 +.PP +.CS +language[_country][.codeset][@modifier] +.CE +.PP +to extract its parts. The initial locale is then set by calling +\fB::msgcat::mclocale\fR with the argument +.PP +.CS +language[_country][_modifier] +.CE +.PP +On Windows and Cygwin, if none of those environment variables is set, +msgcat will attempt to extract locale information from the registry. +From Windows Vista on, the RFC4747 locale name "lang-script-country-options" +is transformed to the locale as "lang_country_script" (Example: +sr-Latn-CS -> sr_cs_latin). For Windows XP, the language id is +transformed analoguously (Example: 0c1a -> sr_yu_cyrillic). +If all these attempts to discover an initial locale from the user's +environment fail, msgcat defaults to an initial locale of +.QW C . +.PP +When a locale is specified by the user, a +.QW "best match" +search is performed during string translation. For example, if a user +specifies +en_GB_Funky, the locales +.QW en_GB_Funky , +.QW en_GB , +.QW en +and +.MT +(the empty string) +are searched in order until a matching translation +string is found. If no translation string is available, then +\fB::msgcat::mcunknown\fR is called. +.SH "NAMESPACES AND MESSAGE CATALOGS" +.PP +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. +.PP +For example, executing the code +.PP +.CS +\fB::msgcat::mcset\fR en hello "hello from ::" +namespace eval foo { + \fB::msgcat::mcset\fR en hello "hello from ::foo" +} +puts [\fB::msgcat::mc\fR hello] +namespace eval foo {puts [\fB::msgcat::mc\fR hello]} +.CE +.PP +will print +.PP +.CS +hello from :: +hello from ::foo +.CE +.PP +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 +.QW inherit +messages from their parent namespace. +.PP +For example, executing (in the +.QW en +locale) the code +.PP +.CS +\fB::msgcat::mcset\fR en m1 ":: message1" +\fB::msgcat::mcset\fR en m2 ":: message2" +\fB::msgcat::mcset\fR en m3 ":: message3" +namespace eval ::foo { + \fB::msgcat::mcset\fR en m2 "::foo message2" + \fB::msgcat::mcset\fR en m3 "::foo message3" +} +namespace eval ::foo::bar { + \fB::msgcat::mcset\fR en m3 "::foo::bar message3" +} +namespace import \fB::msgcat::mc\fR +puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]" +namespace eval ::foo {puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"} +namespace eval ::foo::bar {puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"} +.CE +.PP +will print +.PP +.CS +:: message1; :: message2; :: message3 +:: message1; ::foo message2; ::foo message3 +:: message1; ::foo message2; ::foo::bar message3 +.CE +.SH "LOCATION AND FORMAT OF MESSAGE FILES" +.PP +Message files can be located in any directory, subject +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 msgcat locale specifier (all lowercase) followed by +.QW .msg . +For example: +.PP +.CS +es.msg \(em spanish +en_gb.msg \(em United Kingdom English +.CE +.PP +\fIException:\fR The message file for the root locale +.MT +is called +.QW \fBROOT.msg\fR . +This exception is made so as not to +cause peculiar behavior, such as marking the message file as +.QW hidden +on Unix file systems. +.IP [3] +The file contains a series of calls to \fBmcflset\fR and +\fBmcflmset\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: +.PP +.CS +namespace eval ::mypackage { + \fB::msgcat::mcflset\fR "Free Beer!" "Cerveza Gracias!" +} +.CE +.SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES" +.PP +If a package is installed into a subdirectory of the +\fBtcl_pkgPath\fR and loaded via \fBpackage require\fR, the +following procedure is recommended. +.IP [1] +During package installation, create a subdirectory +\fBmsgs\fR under your package directory. +.IP [2] +Copy your *.msg files into that directory. +.IP [3] +Add the following command to your package initialization script: +.PP +.CS +# load language files, stored in msgs subdirectory +\fB::msgcat::mcload\fR [file join [file dirname [info script]] msgs] +.CE +.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 +might need to be repositioned. For example, it might be +syntactically desirable to rearrange the sentence structure +while translating. +.PP +.CS +format "We produced %d units in location %s" $num $city +format "In location %s we produced %d units" $city $num +.CE +.PP +This can be handled by using the positional +parameters: +.PP +.CS +format "We produced %1\e$d units in location %2\e$s" $num $city +format "In location %2\e$s we produced %1\e$d units" $num $city +.CE +.PP +Similarly, positional parameters can be used with \fBscan\fR to +extract values from internationalized strings. Note that it is not +necessary to pass the output of \fB::msgcat::mc\fR to \fBformat\fR +directly; by passing the values to substitute in as arguments, the +formatting substitution is done directly. +.PP +.CS +\fBmsgcat::mc\fR {Produced %1$d at %2$s} $num $city +# ... where that key is mapped to one of the +# human-oriented versions by \fBmsgcat::mcset\fR +.CE +.SH CREDITS +.PP +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 +.\" Local Variables: +.\" mode: nroff +.\" End: |