2 '\" Copyright (c
) 1998 Mark Harrison
.
4 '\" See the file
"license.terms" for information on usage
and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 '\" SCCS: @(#) msgcat.n
9 '\" The definitions below are for supplemental macros used in Tcl/Tk
12 '\" .AP
type name
in/out ?indent?
13 '\" Start paragraph describing an argument to a library procedure.
14 '\" type is
type of
argument (int, etc
.), in/out is either
"in", "out",
15 '\" or "in/out" to describe whether procedure reads or modifies arg,
16 '\" and indent is equivalent to second arg of
.IP (shouldn
't ever be
17 '\" needed
; use
.AS below instead
)
20 '\" Give maximum sizes of arguments for setting tab stops. Type and
21 '\" name are examples of largest possible arguments that will be passed
22 '\" to .AP later. If args are omitted, default tab stops are used.
25 '\" Start box enclosure
. From here until next
.BE
, everything will be
26 '\" enclosed in one large box.
29 '\" End of box enclosure
.
32 '\" Begin code excerpt.
37 '\" .VS ?version? ?br?
38 '\" Begin vertical sidebar, for use in marking newly-changed parts
39 '\" of man pages
. The first argument is ignored
and used
for recording
40 '\" the version when the .VS was added, so that the sidebars can be
41 '\" found
and removed
when they reach a certain age
. If another argument
42 '\" is present, then a line break is forced before starting the sidebar.
45 '\" End of vertical sidebar
.
48 '\" Begin an indented unfilled display.
51 '\" End of indented unfilled display
.
54 '\" Start of list of standard options for a Tk widget. The
55 '\" options follow on successive lines
, in four columns separated
59 '\" End of
list of standard options
for a Tk widget
.
61 '\" .OP cmdName dbName dbClass
62 '\" Start of description of a specific option. cmdName gives the
63 '\" option
's name as specified in the class command, dbName gives
64 '\" the option
's name in the option database, and dbClass gives
65 '\" the option
's class in the option database.
68 '\" Print arg1 underlined
, then print arg2 normally
.
70 '\" RCS
: @
(#) $Id: msgcat.n,v 1.1 2003/12/20 03:31:54 bbbush Exp $
72 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
76 '\" # Start an argument description
80 . ie !"\\$2"" .TP \\n()Cu
85 \&\\$1 \\fI\\$2\\fP (\\$3)
98 '\" # define tabbing values for .AP
101 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
104 .if !"\\$2
"" .nr
)B
\\w
'\\$2'u
+\\n()Au
+3n
105 .nr
)C
\\n()Bu
+\\w
'(in/out)'u
+2n
107 .AS Tcl_Interp Tcl_CreateInterp
in/out
108 '\" # BS - start boxed text
109 '\" # ^y = starting y location
117 .if n \l'\\n(.lu\
(ul
'
120 '\" # BE - end boxed text (draw box now)
125 .ie n \l
'\\n(^lu\(ul'
127 .\" Draw four
-sided box normally
, but don
't draw top of
128 .\" box if the box started on an earlier page.
130 \h'-1.5n
'\L'|\\n(^yu
-1v
'\l'\\n(^lu
+3n\
(ul
'\L'\\n(^tu
+1v
-\\n(^yu
'\l'|0u-1.5n\
(ul
'
133 \h'-1.5n
'\L'|\\n(^yu
-1v
'\h'\\n(^lu
+3n
'\L'\\n(^tu
+1v
-\\n(^yu
'\l'|0u-1.5n\
(ul
'
140 '\" # VS - start vertical sidebar
141 '\" # ^Y = starting y location
142 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
146 .ie n 'mc \s12\(br\s0
149 '\" # VE - end of vertical sidebar
157 \h
'|\\n(^lu+3n'\L
'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h
'-|\\n(^lu+3n'
164 '\" # Special macro to handle page bottom: finish off current
165 '\" # box/sidebar if in box/sidebar mode, then invoked standard
166 '\" # page bottom macro.
173 .\" Draw three-sided box if this is the box's first page
,
174 .\" draw two sides but no top otherwise
.
175 .ie
!\\n(^b
-1 \h
'-1.5n'\L
'|\\n(^yu-1v'\l
'\\n(^lu+3n\(ul'\L
'\\n(^tu+1v-\\n(^yu'\h
'|0u'\c
176 .el \h
'-1.5n'\L
'|\\n(^yu-1v'\h
'\\n(^lu+3n'\L
'\\n(^tu+1v-\\n(^yu'\h
'|0u'\c
179 .nr ^x
\\n(^tu
+1v
-\\n(^Yu
180 \kx\h
'-\\nxu'\h
'|\\n(^lu+3n'\ky\L
'-\\n(^xu'\v'\\n(^xu'\h
'|0u'\c
193 '\" # DS - begin display
199 '\" # DE - end display
205 '\" # SO - start of list of standard options
207 .SH
"STANDARD OPTIONS"
213 '\" # SE - end of list of standard options
218 See the \\fBoptions\\fR manual entry for details on the standard options.
220 '\" # OP - start of full description for a single option
225 Command
-Line Name
: \\fB
\\$1
\\fR
226 Database Name
: \\fB
\\$2
\\fR
227 Database Class
: \\fB
\\$3
\\fR
231 '\" # CS - begin code excerpt
237 '\" # CE - end code excerpt
245 .TH
"msgcat" n
8.1 Tcl
"Tcl Built-In Commands"
247 '\" Note: do not modify the .SH NAME line immediately below!
249 msgcat \- Tcl message catalog
251 \fBpackage require Tcl 8.2\fR
253 \fBpackage require msgcat 1.1\fR
255 \fB::msgcat::mc \fIsrc-string\fR
257 \fB::msgcat::mclocale \fR?\fInewLocale\fR?
259 \fB::msgcat::mcpreferences\fR
261 \fB::msgcat::mcload \fIdirname\fR
263 \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR?
265 \fB::msgcat::mcunknown \fIlocale src-string\fR
270 The \fBmsgcat\fR package provides a set of functions
271 that can be used to manage multi-lingual user interfaces.
272 Text strings are defined in a ``message catalog'' which
273 is independent from the application, and
274 which can be edited or localized without modifying
275 the application source code. New languages
276 or locales are provided by adding a new file to
279 Use of the message catalog is optional by any application
280 or package, but is encouraged if the application or package
281 wishes to be enabled for multi-lingual applications.
285 \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR?
286 Returns a translation of \fIsrc-string\fR according to the
287 user's current locale
. If additional arguments past
\fIsrc
-string\fR
288 are given
, the
\fBformat
\fR command is used to substitute the
289 additional arguments
in the translation of
\fIsrc
-string\fR
.
291 \fB
::msgcat
::mc
\fR will search the messages defined
292 in the current
namespace for a translation of
\fIsrc
-string\fR
; if
293 none is found
, it will search
in the parent of the current
namespace,
294 and so on until it reaches the global
namespace. If no translation
295 string exists
, \fB
::msgcat
::mcunknown
\fR is called
and the
string
296 returned from
\fB
::msgcat
::mcunknown
\fR is returned
.
298 \fB
::msgcat
::mc
\fR is the main function used to localize an
299 application
. Instead of
using an English
string directly
, an
300 applicaton can pass the English
string through
\fB
::msgcat
::mc
\fR
and
301 use the result
. If an application is written
for a single language
in
302 this fashion
, then it is easy to add support
for additional languages
303 later simply by defining
new message catalog entries
.
305 \fB
::msgcat
::mclocale
\fR?
\fInewLocale
\fR?
306 This function sets the locale to
\fInewLocale
\fR
. If
\fInewLocale
\fR
307 is omitted
, the current locale is returned
, otherwise the current locale
308 is set to
\fInewLocale
\fR
.
309 The initial locale defaults to the locale specified
in
310 the user
's environment. See \fBLOCALE AND SUBLOCALE SPECIFICATION\fR
311 below for a description of the locale string format.
313 \fB::msgcat::mcpreferences\fR
314 Returns an ordered list of the locales preferred by
315 the user, based on the user's language specification
.
316 The
list is ordered from most specific to least
317 preference
. If the user has specified LANG
=en_US_funky
,
318 this procedure would return
{en_US_funky en_US en
}.
320 \fB
::msgcat
::mcload
\fIdirname
\fR
321 Searches the specified directory
for files that
match
322 the language specifications returned by
\fB
::msgcat
::mcpreferences
\fR
.
323 Each file located is sourced
. The file extension is ``
.msg
''.
324 The number of message files which matched the specification
325 and were loaded is returned
.
327 \fB
::msgcat
::mcset
\fIlocale src
-string \fR?
\fItranslate
-string\fR?
328 Sets the translation
for \fIsrc
-string\fR to
\fItranslate
-string\fR
329 in the specified
\fIlocale
\fR
. If
\fItranslate
-string\fR is not
330 specified
, \fIsrc
-string\fR is used
for both
. The function
331 returns
\fItranslate
-string\fR
.
333 \fB
::msgcat
::mcunknown
\fIlocale src
-string\fR
334 This routine is called by
\fB
::msgcat
::mc
\fR
in the case
when
335 a translation
for \fIsrc
-string\fR is not defined
in the
336 current locale
. The default action is to return
337 \fIsrc
-string\fR
. This procedure can be redefined by the
338 application
, for example to log error messages
for each unknown
339 string. The
\fB
::msgcat
::mcunknown
\fR procedure is invoked at the
340 same stack context
as the call to
\fB
::msgcat
::mc
\fR
. The return vaue
341 of
\fB
::msgcat
::mcunknown
\fR is used
as the return vaue
for the call
342 to
\fB
::msgcat
::mc
\fR
.
344 .SH
"LOCALE AND SUBLOCALE SPECIFICATION"
346 The locale is specified by a locale
string.
347 The locale
string consists of
348 a language code
, an optional country code
, and an optional
349 system
-specific code
, each separated by ``
_''. The country
and language
350 codes are specified
in standards ISO
-639 and ISO
-3166.
351 For example
, the locale ``en
'' specifies English
and
352 ``en_US
'' specifes U
.S
. English
.
354 The locale defaults to the value
in \fBenv
(LANG
)\fR at the time the
355 \fBmsgcat
\fR package is loaded
. If
\fBenv
(LANG
)\fR is not defined
, then the
356 locale defaults to ``C
''.
358 When a locale is specified by the user
, a ``best
match'' search is
359 performed during
string translation
. For example
, if a user specifies
360 en_UK_Funky
, the locales ``en_UK_Funky
'', ``en_UK
'', and ``en
'' are
361 searched
in order until a matching translation
string is found
. If no
362 translation
string is available
, then
\fB
::msgcat
::unknown
\fR is
365 .SH
"NAMESPACES AND MESSAGE CATALOGS"
367 Strings stored
in the message catalog are stored relative
368 to the
namespace from which they were added
. This allows
369 multiple packages to use the same strings without fear
370 of collisions with other packages
. It also allows the
371 source
string to be shorter
and less prone to typographical
374 For example
, executing the code
376 mcset en hello
"hello from ::"
377 namespace eval foo
{mcset en hello
"hello from ::foo"}
379 namespace eval foo
{puts
[mc hello
]}
387 When searching
for a translation of a message
, the
388 message catalog will search first the current
namespace,
389 then the parent of the current
namespace, and so on until
390 the global
namespace is reached
. This allows child namespaces
391 to
"inherit" messages from their parent
namespace.
393 For example
, executing the code
395 mcset en m1
":: message1"
396 mcset en m2
":: message2"
397 mcset en m3
":: message3"
398 namespace eval
::foo
{
399 mcset en m2
"::foo message2"
400 mcset en m3
"::foo message3"
402 namespace eval
::foo
::bar
{
403 mcset en m3
"::foo::bar message3"
405 puts
"[mc m1]; [mc m2]; [mc m3]"
406 namespace eval
::foo
{puts
"[mc m1]; [mc m2]; [mc m3]"}
407 namespace eval
::foo
::bar
{puts
"[mc m1]; [mc m2]; [mc m3]"}
411 :: message1
; :: message2
; :: message3
412 :: message1
; ::foo message2
; ::foo message3
413 :: message1
; ::foo message2
; ::foo
::bar message3
416 .SH
"LOCATION AND FORMAT OF MESSAGE FILES"
418 Message files can be located
in any directory
, subject
419 to the following conditions
:
421 All message files
for a package are
in the same directory
.
423 The message file name is a locale specifier followed
424 by ``
.msg
''. For example
:
427 en_UK
.msg
-- UK English
430 The file contains a series of calls to mcset
, setting the
431 necessary translation strings
for the language
. For example
:
433 ::msgcat
::mcset es
"Free Beer!" "Cerveza Gracias!"
436 .SH
"RECOMMENDED MESSAGE SETUP FOR PACKAGES"
438 If a package is installed into a subdirectory of the
439 \fBtcl_pkgPath
\fR
and loaded via
\fBpackage require
\fR
, the
440 following procedure is recommended
.
442 During package installation
, create a subdirectory
443 \fBmsgs
\fR under your package directory
.
445 Copy your
*.msg files into that directory
.
447 Add the following command to your package
448 initialization script
:
450 # load language files, stored in msgs subdirectory
451 ::msgcat
::mcload
[file join
[file dirname
[info script
]] msgs
]
454 .SH
"POSTITIONAL CODES FOR FORMAT AND SCAN COMMANDS"
456 It is possible that a message
string used
as an argument
457 to
\fBformat
\fR might have positionally dependent parameters that
458 might need to be repositioned
. For example
, it might be
459 syntactically desirable to rearrange the sentence structure
462 format
"We produced %d units in location %s" $num $city
463 format
"In location %s we produced %d units" $city $num
466 This can be handled by
using the positional
469 format
"We produced %1\\$d units in location %2\\$s" $num $city
470 format
"In location %2\\$s we produced %1\\$d units" $num $city
473 Similarly
, positional parameters can be used with
\fBscan
\fR to
474 extract values from internationalized strings
.
478 The message catalog code was developed by Mark Harrison
.
481 format(n
), scan(n
), namespace(n
), package(n
)
483 internationalization
, i18n
, localization
, l10n
, message
, text
, translation