1 | '\" |
---|
2 | '\" Copyright (c) 1998 Mark Harrison. |
---|
3 | '\" |
---|
4 | '\" See the file "license.terms" for information on usage and redistribution |
---|
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
6 | '\" |
---|
7 | '\" SCCS: @(#) msgcat.n |
---|
8 | '\" |
---|
9 | .so man.macros |
---|
10 | .TH "msgcat" n 1.4 msgcat "Tcl Bundled Packages" |
---|
11 | .BS |
---|
12 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
13 | .SH NAME |
---|
14 | msgcat \- Tcl message catalog |
---|
15 | .SH SYNOPSIS |
---|
16 | \fBpackage require Tcl 8.5\fR |
---|
17 | .sp |
---|
18 | \fBpackage require msgcat 1.4.2\fR |
---|
19 | .sp |
---|
20 | \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR? |
---|
21 | .sp |
---|
22 | \fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR? |
---|
23 | .sp |
---|
24 | \fB::msgcat::mclocale \fR?\fInewLocale\fR? |
---|
25 | .sp |
---|
26 | \fB::msgcat::mcpreferences\fR |
---|
27 | .sp |
---|
28 | \fB::msgcat::mcload \fIdirname\fR |
---|
29 | .sp |
---|
30 | \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR? |
---|
31 | .sp |
---|
32 | \fB::msgcat::mcmset \fIlocale src-trans-list\fR |
---|
33 | .sp |
---|
34 | \fB::msgcat::mcunknown \fIlocale src-string\fR |
---|
35 | .BE |
---|
36 | .SH DESCRIPTION |
---|
37 | .PP |
---|
38 | The \fBmsgcat\fR package provides a set of functions |
---|
39 | that can be used to manage multi-lingual user interfaces. |
---|
40 | Text strings are defined in a |
---|
41 | .QW "message catalog" |
---|
42 | which is independent from the application, and |
---|
43 | which can be edited or localized without modifying |
---|
44 | the application source code. New languages |
---|
45 | or locales are provided by adding a new file to |
---|
46 | the message catalog. |
---|
47 | .PP |
---|
48 | Use of the message catalog is optional by any application |
---|
49 | or package, but is encouraged if the application or package |
---|
50 | wishes to be enabled for multi-lingual applications. |
---|
51 | .SH COMMANDS |
---|
52 | .TP |
---|
53 | \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR? |
---|
54 | Returns a translation of \fIsrc-string\fR according to the |
---|
55 | user's current locale. If additional arguments past \fIsrc-string\fR |
---|
56 | are given, the \fBformat\fR command is used to substitute the |
---|
57 | additional arguments in the translation of \fIsrc-string\fR. |
---|
58 | .RS |
---|
59 | .PP |
---|
60 | \fB::msgcat::mc\fR will search the messages defined |
---|
61 | in the current namespace for a translation of \fIsrc-string\fR; if |
---|
62 | none is found, it will search in the parent of the current namespace, |
---|
63 | and so on until it reaches the global namespace. If no translation |
---|
64 | string exists, \fB::msgcat::mcunknown\fR is called and the string |
---|
65 | returned from \fB::msgcat::mcunknown\fR is returned. |
---|
66 | .PP |
---|
67 | \fB::msgcat::mc\fR is the main function used to localize an |
---|
68 | application. Instead of using an English string directly, an |
---|
69 | application can pass the English string through \fB::msgcat::mc\fR and |
---|
70 | use the result. If an application is written for a single language in |
---|
71 | this fashion, then it is easy to add support for additional languages |
---|
72 | later simply by defining new message catalog entries. |
---|
73 | .RE |
---|
74 | .TP |
---|
75 | \fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR? |
---|
76 | Given several source strings, \fB::msgcat::mcmax\fR returns the length |
---|
77 | of the longest translated string. This is useful when designing |
---|
78 | localized GUIs, which may require that all buttons, for example, be a |
---|
79 | fixed width (which will be the width of the widest button). |
---|
80 | .TP |
---|
81 | \fB::msgcat::mclocale \fR?\fInewLocale\fR? |
---|
82 | This function sets the locale to \fInewLocale\fR. If \fInewLocale\fR |
---|
83 | is omitted, the current locale is returned, otherwise the current locale |
---|
84 | is set to \fInewLocale\fR. msgcat stores and compares the locale in a |
---|
85 | case-insensitive manner, and returns locales in lowercase. |
---|
86 | The initial locale is determined by the locale specified in |
---|
87 | the user's environment. See \fBLOCALE SPECIFICATION\fR |
---|
88 | below for a description of the locale string format. |
---|
89 | .TP |
---|
90 | \fB::msgcat::mcpreferences\fR |
---|
91 | Returns an ordered list of the locales preferred by |
---|
92 | the user, based on the user's language specification. |
---|
93 | The list is ordered from most specific to least |
---|
94 | preference. The list is derived from the current |
---|
95 | locale set in msgcat by \fB::msgcat::mclocale\fR, and |
---|
96 | cannot be set independently. For example, if the |
---|
97 | current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR |
---|
98 | .VS 1.4 |
---|
99 | returns \fB{en_US_funky en_US en {}}\fR. |
---|
100 | .VE 1.4 |
---|
101 | .TP |
---|
102 | \fB::msgcat::mcload \fIdirname\fR |
---|
103 | Searches the specified directory for files that match |
---|
104 | the language specifications returned by \fB::msgcat::mcpreferences\fR |
---|
105 | (note that these are all lowercase), extended by the file extension |
---|
106 | .QW .msg . |
---|
107 | Each matching file is |
---|
108 | read in order, assuming a UTF-8 encoding. The file contents are |
---|
109 | then evaluated as a Tcl script. This means that Unicode characters |
---|
110 | may be present in the message file either directly in their UTF-8 |
---|
111 | encoded form, or by use of the backslash-u quoting recognized by Tcl |
---|
112 | evaluation. The number of message files which matched the specification |
---|
113 | and were loaded is returned. |
---|
114 | .TP |
---|
115 | \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR? |
---|
116 | Sets the translation for \fIsrc-string\fR to \fItranslate-string\fR |
---|
117 | in the specified \fIlocale\fR and the current namespace. If |
---|
118 | \fItranslate-string\fR is not specified, \fIsrc-string\fR is used |
---|
119 | for both. The function returns \fItranslate-string\fR. |
---|
120 | .TP |
---|
121 | \fB::msgcat::mcmset \fIlocale src-trans-list\fR |
---|
122 | Sets the translation for multiple source strings in |
---|
123 | \fIsrc-trans-list\fR in the specified \fIlocale\fR and the current |
---|
124 | namespace. |
---|
125 | \fIsrc-trans-list\fR must have an even number of elements and is in |
---|
126 | the form {\fIsrc-string translate-string\fR ?\fIsrc-string |
---|
127 | translate-string ...\fR?} \fB::msgcat::mcmset\fR can be significantly |
---|
128 | faster than multiple invocations of \fB::msgcat::mcset\fR. The function |
---|
129 | returns the number of translations set. |
---|
130 | .TP |
---|
131 | \fB::msgcat::mcunknown \fIlocale src-string\fR |
---|
132 | This routine is called by \fB::msgcat::mc\fR in the case when |
---|
133 | a translation for \fIsrc-string\fR is not defined in the |
---|
134 | current locale. The default action is to return |
---|
135 | \fIsrc-string\fR. This procedure can be redefined by the |
---|
136 | application, for example to log error messages for each unknown |
---|
137 | string. The \fB::msgcat::mcunknown\fR procedure is invoked at the |
---|
138 | same stack context as the call to \fB::msgcat::mc\fR. The return value |
---|
139 | of \fB::msgcat::mcunknown\fR is used as the return value for the call |
---|
140 | to \fB::msgcat::mc\fR. |
---|
141 | .SH "LOCALE SPECIFICATION" |
---|
142 | .PP |
---|
143 | The locale is specified to \fBmsgcat\fR by a locale string |
---|
144 | passed to \fB::msgcat::mclocale\fR. |
---|
145 | The locale string consists of |
---|
146 | a language code, an optional country code, and an optional |
---|
147 | system-specific code, each separated by |
---|
148 | .QW _ . |
---|
149 | The country and language |
---|
150 | codes are specified in standards ISO-639 and ISO-3166. |
---|
151 | For example, the locale |
---|
152 | .QW en |
---|
153 | specifies English and |
---|
154 | .QW en_US |
---|
155 | specifies U.S. English. |
---|
156 | .PP |
---|
157 | When the msgcat package is first loaded, the locale is initialized |
---|
158 | according to the user's environment. The variables \fBenv(LC_ALL)\fR, |
---|
159 | \fBenv(LC_MESSAGES)\fR, and \fBenv(LANG)\fR are examined in order. |
---|
160 | The first of them to have a non-empty value is used to determine the |
---|
161 | initial locale. The value is parsed according to the XPG4 pattern |
---|
162 | .CS |
---|
163 | language[_country][.codeset][@modifier] |
---|
164 | .CE |
---|
165 | to extract its parts. The initial locale is then set by calling |
---|
166 | \fB::msgcat::mclocale\fR with the argument |
---|
167 | .CS |
---|
168 | language[_country][_modifier] |
---|
169 | .CE |
---|
170 | On Windows, if none of those environment variables is set, msgcat will |
---|
171 | attempt to extract locale information from the |
---|
172 | registry. If all these attempts to discover an initial locale |
---|
173 | from the user's environment fail, msgcat defaults to an initial |
---|
174 | locale of |
---|
175 | .QW C . |
---|
176 | .PP |
---|
177 | When a locale is specified by the user, a |
---|
178 | .QW "best match" |
---|
179 | search is performed during string translation. For example, if a user |
---|
180 | specifies |
---|
181 | .VS 1.4 |
---|
182 | en_GB_Funky, the locales |
---|
183 | .QW en_GB_Funky , |
---|
184 | .QW en_GB , |
---|
185 | .QW en |
---|
186 | and |
---|
187 | .MT |
---|
188 | (the empty string) |
---|
189 | .VE 1.4 |
---|
190 | are searched in order until a matching translation |
---|
191 | string is found. If no translation string is available, then |
---|
192 | \fB::msgcat::mcunknown\fR is called. |
---|
193 | .SH "NAMESPACES AND MESSAGE CATALOGS" |
---|
194 | .PP |
---|
195 | Strings stored in the message catalog are stored relative |
---|
196 | to the namespace from which they were added. This allows |
---|
197 | multiple packages to use the same strings without fear |
---|
198 | of collisions with other packages. It also allows the |
---|
199 | source string to be shorter and less prone to typographical |
---|
200 | error. |
---|
201 | .PP |
---|
202 | For example, executing the code |
---|
203 | .CS |
---|
204 | \fB::msgcat::mcset\fR en hello "hello from ::" |
---|
205 | namespace eval foo { |
---|
206 | \fB::msgcat::mcset\fR en hello "hello from ::foo" |
---|
207 | } |
---|
208 | puts [\fB::msgcat::mc\fR hello] |
---|
209 | namespace eval foo {puts [\fB::msgcat::mc\fR hello]} |
---|
210 | .CE |
---|
211 | will print |
---|
212 | .CS |
---|
213 | hello from :: |
---|
214 | hello from ::foo |
---|
215 | .CE |
---|
216 | .PP |
---|
217 | When searching for a translation of a message, the |
---|
218 | message catalog will search first the current namespace, |
---|
219 | then the parent of the current namespace, and so on until |
---|
220 | the global namespace is reached. This allows child namespaces to |
---|
221 | .QW inherit |
---|
222 | messages from their parent namespace. |
---|
223 | .PP |
---|
224 | For example, executing (in the |
---|
225 | .QW en |
---|
226 | locale) the code |
---|
227 | .CS |
---|
228 | \fB::msgcat::mcset\fR en m1 ":: message1" |
---|
229 | \fB::msgcat::mcset\fR en m2 ":: message2" |
---|
230 | \fB::msgcat::mcset\fR en m3 ":: message3" |
---|
231 | namespace eval ::foo { |
---|
232 | \fB::msgcat::mcset\fR en m2 "::foo message2" |
---|
233 | \fB::msgcat::mcset\fR en m3 "::foo message3" |
---|
234 | } |
---|
235 | namespace eval ::foo::bar { |
---|
236 | \fB::msgcat::mcset\fR en m3 "::foo::bar message3" |
---|
237 | } |
---|
238 | namespace import \fB::msgcat::mc\fR |
---|
239 | puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]" |
---|
240 | namespace eval ::foo {puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"} |
---|
241 | namespace eval ::foo::bar {puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"} |
---|
242 | .CE |
---|
243 | will print |
---|
244 | .CS |
---|
245 | :: message1; :: message2; :: message3 |
---|
246 | :: message1; ::foo message2; ::foo message3 |
---|
247 | :: message1; ::foo message2; ::foo::bar message3 |
---|
248 | .CE |
---|
249 | .SH "LOCATION AND FORMAT OF MESSAGE FILES" |
---|
250 | .PP |
---|
251 | Message files can be located in any directory, subject |
---|
252 | to the following conditions: |
---|
253 | .IP [1] |
---|
254 | All message files for a package are in the same directory. |
---|
255 | .IP [2] |
---|
256 | The message file name is a msgcat locale specifier (all lowercase) followed by |
---|
257 | .QW .msg . |
---|
258 | For example: |
---|
259 | .CS |
---|
260 | es.msg \(em spanish |
---|
261 | en_gb.msg \(em United Kingdom English |
---|
262 | .CE |
---|
263 | .VS 1.4 |
---|
264 | \fIException:\fR The message file for the root locale |
---|
265 | .MT |
---|
266 | is called |
---|
267 | .QW \fBROOT.msg\fR . |
---|
268 | This exception is made so as not to |
---|
269 | cause peculiar behavior, such as marking the message file as |
---|
270 | .QW hidden |
---|
271 | on Unix file systems. |
---|
272 | .VE 1.4 |
---|
273 | .IP [3] |
---|
274 | The file contains a series of calls to \fBmcset\fR and |
---|
275 | \fBmcmset\fR, setting the necessary translation strings |
---|
276 | for the language, likely enclosed in a \fBnamespace eval\fR |
---|
277 | so that all source strings are tied to the namespace of |
---|
278 | the package. For example, a short \fBes.msg\fR might contain: |
---|
279 | .CS |
---|
280 | namespace eval ::mypackage { |
---|
281 | \fB::msgcat::mcset\fR es "Free Beer!" "Cerveza Gracias!" |
---|
282 | } |
---|
283 | .CE |
---|
284 | .SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES" |
---|
285 | .PP |
---|
286 | If a package is installed into a subdirectory of the |
---|
287 | \fBtcl_pkgPath\fR and loaded via \fBpackage require\fR, the |
---|
288 | following procedure is recommended. |
---|
289 | .IP [1] |
---|
290 | During package installation, create a subdirectory |
---|
291 | \fBmsgs\fR under your package directory. |
---|
292 | .IP [2] |
---|
293 | Copy your *.msg files into that directory. |
---|
294 | .IP [3] |
---|
295 | Add the following command to your package |
---|
296 | initialization script: |
---|
297 | .CS |
---|
298 | # load language files, stored in msgs subdirectory |
---|
299 | \fB::msgcat::mcload\fR [file join [file dirname [info script]] msgs] |
---|
300 | .CE |
---|
301 | .SH "POSITIONAL CODES FOR FORMAT AND SCAN COMMANDS" |
---|
302 | .PP |
---|
303 | It is possible that a message string used as an argument |
---|
304 | to \fBformat\fR might have positionally dependent parameters that |
---|
305 | might need to be repositioned. For example, it might be |
---|
306 | syntactically desirable to rearrange the sentence structure |
---|
307 | while translating. |
---|
308 | .CS |
---|
309 | format "We produced %d units in location %s" $num $city |
---|
310 | format "In location %s we produced %d units" $city $num |
---|
311 | .CE |
---|
312 | .PP |
---|
313 | This can be handled by using the positional |
---|
314 | parameters: |
---|
315 | .CS |
---|
316 | format "We produced %1\e$d units in location %2\e$s" $num $city |
---|
317 | format "In location %2\e$s we produced %1\e$d units" $num $city |
---|
318 | .CE |
---|
319 | .PP |
---|
320 | Similarly, positional parameters can be used with \fBscan\fR to |
---|
321 | extract values from internationalized strings. |
---|
322 | .SH CREDITS |
---|
323 | .PP |
---|
324 | The message catalog code was developed by Mark Harrison. |
---|
325 | .SH "SEE ALSO" |
---|
326 | format(n), scan(n), namespace(n), package(n) |
---|
327 | .SH KEYWORDS |
---|
328 | internationalization, i18n, localization, l10n, message, text, translation |
---|