'\"
'\" 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