diff options
Diffstat (limited to 'doc/msgcat.n')
| -rw-r--r-- | doc/msgcat.n | 99 |
1 files changed, 77 insertions, 22 deletions
diff --git a/doc/msgcat.n b/doc/msgcat.n index 4ed83eb..bae6dbe 100644 --- a/doc/msgcat.n +++ b/doc/msgcat.n @@ -4,10 +4,8 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" SCCS: @(#) msgcat.n -'\" +.TH "msgcat" n 1.5 msgcat "Tcl Bundled Packages" .so man.macros -.TH "msgcat" n 1.4 msgcat "Tcl Bundled Packages" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -15,7 +13,7 @@ msgcat \- Tcl message catalog .SH SYNOPSIS \fBpackage require Tcl 8.5\fR .sp -\fBpackage require msgcat 1.4.2\fR +\fBpackage require msgcat 1.5\fR .sp \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR? .sp @@ -31,7 +29,13 @@ msgcat \- Tcl message catalog .sp \fB::msgcat::mcmset \fIlocale src-trans-list\fR .sp -\fB::msgcat::mcunknown \fIlocale src-string\fR +.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 @@ -133,12 +137,33 @@ 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::mcunknown \fIlocale src-string\fR +\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. This procedure can be redefined by the +\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 @@ -165,19 +190,26 @@ 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 -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 +.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 @@ -204,15 +236,18 @@ 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" + \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 @@ -228,23 +263,26 @@ messages from their parent namespace. 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" + \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" + \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 @@ -260,10 +298,12 @@ All message files for a package are in the same directory. 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 @@ -273,14 +313,15 @@ 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 \fBmcset\fR and -\fBmcmset\fR, setting the necessary translation strings +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::mcset\fR es "Free Beer!" "Cerveza Gracias!" + \fB::msgcat::mcflset\fR "Free Beer!" "Cerveza Gracias!" } .CE .SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES" @@ -294,8 +335,8 @@ During package installation, create a subdirectory .IP [2] Copy your *.msg files into that directory. .IP [3] - Add the following command to your package -initialization script: +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] @@ -307,6 +348,7 @@ 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 @@ -314,13 +356,23 @@ format "In location %s we produced %d units" $city $num .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. +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. @@ -328,3 +380,6 @@ The message catalog code was developed by Mark Harrison. format(n), scan(n), namespace(n), package(n) .SH KEYWORDS internationalization, i18n, localization, l10n, message, text, translation +.\" Local Variables: +.\" mode: nroff +.\" End: |