'\"
'\" 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.
'\" 
'\" SCCS: @(#) msgcat.n
'\" 
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The
'\"	options follow on successive lines, in four columns separated
'\"	by tabs.
'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: msgcat.n,v 1.2 2003/11/24 05:09:59 bbbush Exp $
'\"
'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.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
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "msgcat" 3tcl 8.1 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
msgcat \- Tcl 訊息目錄
.SH "總覽 SYNOPSIS"
\fBpackage require Tcl 8.2\fR
.sp
\fBpackage require msgcat 1.1\fR
.sp
\fB::msgcat::mc \fIsrc-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::mcunknown \fIlocale src-string\fR
.BE

.SH "描述 DESCRIPTION"
.PP
\fBmsgcat\fR 包提供用來管理多語言的使用者介面的一系列函式。在獨立於應用的一個“訊息目錄”中定義文字串，可以編輯和修改這些文字串而不用修改應用的原始碼。透過向這個訊息目錄增加一個新檔案來提供一個新語言或地域(locale)。
.PP
對任何應用和包使用訊息目錄都是可選的，但是鼓勵你使用它，以便應用或包在多語言環境中被採用。                 

.SH "命令 COMMANDS
.TP
\fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR?
依照使用者的當前地區，返回 \fIsrc-string\fR   的翻譯(translation)。如果在 \fIsrc-string\fR 之後給出了附加的引數，使用 \fBformat\fR  命令把 \fIsrc-string\fR\fI \fR的翻譯中的轉換指定符替換成補充引數。

為了翻譯 \fIsrc-string \fR\fB::msgcat::mc\fR  將在當前名字空間中查詢定義的訊息；如果未找到，它將在當前的名字空間的父空間中查詢，以此類推直到到達全域性名字空間。如果不存在轉換字串，呼叫 \fB::msgcat::mcunknown\fR 並返回 \fB::msgcat::mcunknown\fR  的返回。
.PP
\fB::msgcat::mc\fR  是用來本地化一個應用的主要函式。不再直接的使用英文字串，一個應用可以把英文字串傳遞給 \fB::msgcat::mc\fR 並使用它的結果。如果以這種方式用一種語言寫了一個應用，透過簡單的定義新的訊息目錄條目，以後增加附加的語言支援是很容易的。
.TP
\fB::msgcat::mclocale \fR?\fInewLocale\fR? 
這個函式把地域設定成 \fInewLocale\fR。如果省略了 \fInewLocale\fR，返回當前的地域，否則當前的地域被設定成 \fInewLocale\fR。初始的地域預設為在使用者的環境變數中指定的地域。關於地域字串的格式的詳細描述參見下面的 \fBLOCALE AND SUBLOCALE SPECIFICATION\fR 地域和子地域指定章節。   
.TP
\fB::msgcat::mcpreferences\fR
返回一個有序的地域列表，它們是基於使用者指定的語言，以使用者喜好程度為次序。次序是從最偏好到最不喜好的。如果使用者已經指定了LANG=en_US_funky，這個過程將返回{en_US_funky en_US en}。
.TP
\fB::msgcat::mcload \fIdirname\fR
在指定的目錄中查詢一個檔案，這個檔案匹配用 \fB::msgcat::mcpreferences \fR返回的語言指定。每個檔案的根檔名是地域字串，副檔名是“.msg”。返回匹配的指定和裝載了訊息的數目。 
.TP
\fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR?
在指定的 \fIlocale \fR中設定從 \fIsrc-string\fR  到 \fItranslate-string\fR  的翻譯。如果未指定 \fItranslate-string\fR，對二者都使用 \fIsrc-string\fR 。函式返回 \fItranslate-string\fR。  
.TP
\fB::msgcat::mcunknown \fIlocale src-string\fR
在當前的地域中沒有給 \fIsrc-string\fR 定義的翻譯的情況下，這個例程被 \fB::msgcat::mc\fR  呼叫。預設的動作是返回  \fIsrc-string\fR。這個過程可以被這個應用重新定義，比如對每個未知字串記錄錯誤訊息日誌。在與 \fB::msgcat::mc \fR相同的棧層次上呼叫 \fB::msgcat::mcunknown\fR 過程。 \fB::msgcat::mcunknown\fR  的返回值被用做 \fB::msgcat::mc \fR的返回值。 

.SH "地域和子地域規定 LOCALE AND SUBLOCALE SPECIFICATION"
.PP
用地域字串指定地域。地域字串的組成是一個語言程式碼，一個可選的國家(地區)程式碼，一個可選的特定於系統程式碼，它們用“_”分割。國家和語言程式碼在標準ISO-639 和 ISO-3166 中。例如，地域“en”指定 English 而“en_US”指定  U.S.  English。
.PP
區域定義預設為裝載 \fBmsgcat \fR包時在 \fBenv(LANG) \fR中的值。如果未定義 \fBenv(LANG)\fR，則地域預設為“C”。
.PP
在使用者指定一個地域的時候，在字串翻譯期間進行“最佳匹配”查詢。例如，如果使用者指定了 en_UK_Funky，按“en_UK_Funky”、“en_UK”、和“en” 的次序查詢地域，直到找到一個匹配的字串翻譯。如果沒有找到這個字串的翻譯，則呼叫 \fB::msgcat::unknown\fR。
.PP
譯註：常用地域字串的一部分
.CS
語言	國家(地區)	地域 ID
Arabic	Saudi Arabia	ar_SA
Chinese (Simplified)	China	zh_CN
Chinese (Traditional)	Taiwan	zh_TW
English	United States	en_US
French	France	fr_FR
German	Germany	de_DE
Hebrew	Israel	iw_IL
Italian	Italy	it_IT
Japanese	Japan	ja_JP
Korean	South Koreako_KR
Spanish	Spain	es_ES
Swedish	Sweden	sv_SE
.CE

.SH NAME
.PP
在訊息目錄中儲存的字串被儲存為相對於在其中增加它們的那個名字空間。這允許多個包使用相同的字串而不用害怕與其他包衝突。它還允許源字串被縮寫而減少(less prone to)排字錯誤。    
.PP
例如，執行程式碼 
.CS
mcset en hello "hello from ::"
namespace eval foo {mcset en hello "hello from ::foo"}
puts [mc hello]
namespace eval foo {puts [mc hello]}
.CE
將輸出   
.CS
hello from ::
hello from ::foo
.CE
.PP
在查詢一個訊息的翻譯的時候，訊息目錄將首先查詢當前名字空間，接著是當前名字空間的父名字空間，以次類推知道到達全域性名字空間。這允許子名字空間從它的父名字空間“繼承”訊息。
.PP
例如，執行程式碼        
.CS
mcset en m1 ":: message1"
mcset en m2 ":: message2"
mcset en m3 ":: message3"
namespace eval ::foo {
    mcset en m2 "::foo message2"
    mcset en m3 "::foo message3"
}
namespace eval ::foo::bar {
    mcset en m3 "::foo::bar message3"
}
puts "[mc m1]; [mc m2]; [mc m3]"
namespace eval ::foo {puts "[mc m1]; [mc m2]; [mc m3]"}
namespace eval ::foo::bar {puts "[mc m1]; [mc m2]; [mc m3]"}
.CE
將輸出
.CS
:: message1; :: message2; :: message3
:: message1; ::foo message2; ::foo message3
:: message1; ::foo message2; ::foo::bar message3
.CE

.SH "訊息檔案的定位和格式 LOCATION AND FORMAT OF MESSAGE FILES"
.PP
訊息檔案可以位於任何目錄中，取決於下列條件:
.IP [1]
給一個包的所有訊息檔案都在相同的目錄中。  
.IP [2]
訊息檔名跟一個地域指定符並跟隨著“.msg”。例如:        
.CS
es.msg    -- spanish
en_UK.msg -- UK English
.CE
.IP [3]
這個檔案包含一系列對 mcset 的呼叫，它們為這個語言設定需要的翻譯字串。例如:   
.CS
::msgcat::mcset es "Free Beer!" "Cerveza Gracias!"
.CE

.SH "推薦的對包的訊息設定 RECOMMENDED MESSAGE SETUP FOR PACKAGES"
.PP
如果一個包被安裝到\fBtcl_pkgPath\fR  的一個子目錄中並透過 \fBpackage require\fR 裝載，推薦下列過程。
.IP [1]
在包安裝期間，在你的包目錄下建立一個子目錄\fBmsgs\fR。     
.IP [2]
複製你的 *.msg 檔案到這個目錄中。    
.IP [3]
在你的包初始化指令碼中增加下列命令:          
.CS
# load language files, stored in msgs subdirectory
::msgcat::mcload [file join [file dirname [info script]] msgs]
.CE

.SH "給 FORMAT 和 SCAN 命令的定位程式碼 POSTITIONAL CODES FOR FORMAT AND SCAN COMMANDS"
.PP
用做給 \fBformat\fR 的引數的一個訊息字串中的轉換指定符可以包含一個 XPG3 位置指定符。例如，它可以按句法的需要在翻譯的時候重新安排句子結構。  
.CS
format "We produced %d units in location %s" $num $city
format "In location %s we produced %d units" $city $num
.CE
.PP
可使用定位引數來處理:   
.CS
format "We produced %1\\$d units in location %2\\$s" $num $city
format "In location %2\\$s we produced %1\\$d units" $num $city
.CE
.PP
類似的，可以在 \fBscan\fR 中使用定位引數來提取國際化字串中的值。

.SH "感謝 CREDITS"
.PP
訊息目錄程式碼由 Mark Harrison 開發。  

.SH "參見 SEE ALSO"
format(n), scan(n), namespace(n), package(n)

.SH "關鍵字 KEYWORDS"
internationalization, i18n, localization, l10n, message, text, translation

.SH "[中文版維護人]"
.B 寒蟬退士
.CS
譯註：部分句子寫的莫名其妙，餘加以意譯。
.CE
.SH "[中文版最新更新]"
.B 2001/10/12
.SH "《中國 Linux 論壇 man 手冊頁翻譯計劃》:"
.BI http://cmpp.linuxforum.net
.SH "跋"
.br
本頁面中文版由中文 man 手冊頁計劃提供。
.br
中文 man 手冊頁計劃：\fBhttps://github.com/man-pages-zh/manpages-zh\fR