.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Locale::Po4a::Po 3pm"
.TH Locale::Po4a::Po 3pm "2023-01-03" "Po4a 工具" "Po4a 工具"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "名稱"
.IX Header "名稱"
Locale::Po4a::Po \- \s-1PO\s0 檔案操作模組
.SH "簡介"
.IX Header "簡介"
.Vb 2
\&    use Locale::Po4a::Po;
\&    my $pofile=Locale::Po4a::Po\->new();
\&
\&    # 讀取 PO 檔案
\&    $pofile\->read(\*(Aqfile.po\*(Aq);
\&
\&    # 新增條目
\&    $pofile\->push(\*(Aqmsgid\*(Aq => \*(AqHello\*(Aq, \*(Aqmsgstr\*(Aq => \*(Aq你好\*(Aq,
\&                  \*(Aqflags\*(Aq => "wrap", \*(Aqreference\*(Aq=>\*(Aqfile.c:46\*(Aq);
\&
\&    # 提取翻譯
\&    $pofile\->gettext("Hello"); # 返回 \*(Aqbonjour\*(Aq
\&
\&    # 寫回檔案
\&    $pofile\->write(\*(Aqotherfile.po\*(Aq);
.Ve
.SH "描述"
.IX Header "描述"
Locale::Po4a::Po 是一個允許您操作訊息目錄的模組。您可以從/向檔案 (其副檔名通常是 \fIpo\fR) 載入和寫入，您可以動態構建新條目或請求字串翻譯。
.PP
有關 \s-1PO\s0 格式的訊息目錄及其使用的更完整說明，請參閱 gettext 程式(節點\*(L"'\s-1PO\s0 文件\*(R"')的資訊文件。
.PP
此模組是 po4a 專案的一部分，該專案的目標是使用 \s-1PO\s0 檔案(在原始位置設計用於簡化程式訊息的翻譯)來翻譯所有內容，包括文件(手冊頁、資訊手冊)、軟體包說明、debconf 模板以及可能從中受益的所有內容。
.SH "此模組接受的選項"
.IX Header "此模組接受的選項"
.IP "\fB\-\-porefs\fR \fItype\fR" 4
.IX Item "--porefs type"
指定引用格式。引數 \fItype\fR 可以是以下值之一：\fBnever\fR 不生成任何引用；\fBfile\fR 只指定不帶行號的檔案；\fBcounter\fR 用遞增的計數器替換行號；\fBfull\fR 包含完整引用（預設值：full）。
.IP "\fB\-\-wrap\-po\fR \fBno\fR|\fBnewlines\fR|\fInumber\fR (default: 76)" 4
.IX Item "--wrap-po no|newlines|number (default: 76)"
指定應如何封裝 po 檔案。這使我們可以選擇封裝良好但可能導致 git 衝突的檔案，或者更容易自動處理但對人類來說更難讀取的檔案。
.Sp
從歷史上看，gettext 套件已經重新格式化了第 77 列化妝品的 po 檔案。此選項指定 po4a 的行為。如果設定為數值，po4a 將在內容中的此列和換行之後封裝 po 檔案。如果設定為 \fBnewlines\fR，po4a 將只在內容中的新行之後拆分 msgid 和 msgstr。如果設置為 \fBno\fR，則 po4a 根本不會封裝 po 檔案。引用註釋總是由我們在內部使用的 gettext 工具封裝。
.Sp
請注意，此選項對 msgid 和 msgstr 的封裝方式（即，將換行符新增到這些字串的內容中）沒有影響。
.IP "\fB\-\-msgid\-bugs\-address\fR \fIemail@address\fR" 4
.IX Item "--msgid-bugs-address email@address"
設定 msgid 錯誤的報告地址。 預設情況下，建立的 \s-1POT\s0 檔案沒有 Report-Msgid-Bugs-To 欄位。
.IP "\fB\-\-copyright\-holder\fR \fIstring\fR" 4
.IX Item "--copyright-holder string"
在 \s-1POT\s0 標頭中設定版權所有者。 預設值為“自由軟體基金會有限公司。”
.IP "\fB\-\-package\-name\fR \fIstring\fR" 4
.IX Item "--package-name string"
設定 \s-1POT\s0 標頭的程式包名稱。 預設值為“封裝”。
.IP "\fB\-\-package\-version\fR \fIstring\fR" 4
.IX Item "--package-version string"
設定 \s-1POT\s0 標頭的軟體包版本。 預設值為“版本”。
.SH "有關整個訊息目錄的函式"
.IX Header "有關整個訊息目錄的函式"
.IP "\fBnew()\fR" 4
.IX Item "new()"
建立新的訊息目錄。如果提供了引數，則它是我們應該載入的 \s-1PO\s0 檔案的名稱。
.IP "read($)" 4
.IX Item "read($)"
讀取 \s-1PO\s0 檔案(其名稱作為引數給定)。self 中以前存在的條目不會刪除，新條目會新增到目錄的末尾。
.IP "write($)" 4
.IX Item "write($)"
將當前目錄寫入給定檔案。
.IP "write_if_needed($$)" 4
.IX Item "write_if_needed($$)"
與 write 類似，但如果 \s-1PO\s0 或 \s-1POT\s0 檔案已經存在，則物件將被寫入臨時檔案中，該臨時檔案將與現有檔案進行比較，以檢查是否需要更新 (這避免了僅僅為了更新線參考或 POT-Creation-Date 欄位而更改 \s-1POT\s0)。
.IP "filter($)" 4
.IX Item "filter($)"
此函式用於從現有目錄中提取目錄。只有在給定檔案中有引用的條目才會放入結果目錄中。
.Sp
該函式解析其引數，將其轉換為 Perl 函式定義，計算該定義的值，並篩選該函式返回 true 的欄位。
.Sp
我有時喜歡 Perl ;)
.IP "\fBto_utf8()\fR" 4
.IX Item "to_utf8()"
重新編碼為UTF\-8 PO的訊息。如果 \s-1PO\s0 檔案中沒有指定字符集 (\*(L"\s-1CHARSET\*(R"\s0 值)，或者它已經是 \s-1UTF\-8\s0 或 ASCII，則不執行任何操作。
.SH "使用訊息目錄進行翻譯的函式"
.IX Header "使用訊息目錄進行翻譯的函式"
.IP "gettext($%)" 4
.IX Item "gettext($%)"
請求翻譯當前目錄中作為引數給定的字串。如果未找到原始 (未翻譯) 字串，該函數將返回該字串。
.Sp
在要轉換的字串之後，可以傳遞一組額外的引數。以下是有效的條目：
.RS 4
.IP "\fBwrap\fR" 4
.IX Item "wrap"
指示我們是否可以認為字串中的空格不重要的布林值。如果是，則該函式在查詢翻譯之前對字串進行規範化，並對結果進行封裝。
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
我們應該換行的列 (預設值：76)。
.RE
.RS 4
.RE
.IP "\fBstats_get()\fR" 4
.IX Item "stats_get()"
返回自上次呼叫 \fBstats_clear()\fR 以來 gettext 命中率的統計資訊。請注意，它與 msgfmt \-\-statistic 列印的統計資料不同。這裡，它是關於 \s-1PO\s0 檔案最近使用情況的統計資訊，而 msgfmt 報告檔案的狀態。使用示例：
.Sp
.Vb 1
\&    [使用 PO 檔案翻譯內容]
\&
\&    ($percent,$hit,$queries) = $pofile\->stats_get();
\&    print "So far, we found translations for $percent\e%  ($hit of $queries) of strings.\en";
.Ve
.IP "\fBstats_clear()\fR" 4
.IX Item "stats_clear()"
清除有關 gettext 命中的統計資訊。
.SH "用於構建訊息目錄的函式"
.IX Header "用於構建訊息目錄的函式"
.IP "push(%)" 4
.IX Item "push(%)"
在當前目錄的末尾推送新條目。引數應形成雜湊表。有效金鑰為：
.RS 4
.IP "\fBmsgid\fR" 4
.IX Item "msgid"
原始語言的字串。
.IP "\fBmsgstr\fR" 4
.IX Item "msgstr"
翻譯。
.IP "\fBreference\fR" 4
.IX Item "reference"
指示找到此字串的地點。示例：file.c:46(意思是在第 46 行的 'file.c' 中)。它可以是空格分隔列表，以防發生多次。
.IP "\fBcomment\fR" 4
.IX Item "comment"
此處手動新增的評論（由翻譯人員）。此處的格式是免費的。
.IP "\fBautomatic\fR" 4
.IX Item "automatic"
由字串提取程式自動新增的註釋。有關詳細資訊，請參閱 \fB\-\-add\-comments\fR 程式的 \fBxgettext\fR 選項。
.IP "\fBflags\fR" 4
.IX Item "flags"
此條目的所有已定義標誌的以空格分隔的列表。
.Sp
有效標誌為： \fBc\-text\fR, \fBpython-text\fR, \fBlisp-text\fR, \fBelisp-text\fR, \fBlibrep-text\fR, \fBsmalltalk-text\fR, \fBjava-text\fR, \fBawk-text\fR, \fBobject-pascal-text\fR, \fBycp-text\fR, \fBtcl-text\fR, \fBwrap\fR, \fBno-wrap\fR 和 \fBfuzzy\fR.
.Sp
有關它們的含義，請參閱 gettext 文件。
.IP "\fBtype\fR" 4
.IX Item "type"
這主要是一個內部引數：它是在對文件進行獲取文字化時使用的。這裡的想法是將原始和翻譯都解析成 \s-1PO\s0 物件，並將它們合併，使用一個的 msgid 作為 msgid，使用另一個的 msgid 作為 msgstr。為了確保一切正常，PO 物件中的每個 msgid 都根據它們的結構 (就像 DocBook 中的 \*(L"chapt\*(R"、\*(L"sect1\*(R"、\*(L"p\*(R" 等)被賦予一個型別。如果字元串型別不同，則意味著兩個檔案不共享相同的結構，並且該過程會報告錯誤。
.Sp
此資訊在 \s-1PO\s0 檔案中作為自動註釋寫入，因為這為翻譯人員提供了有關要翻譯的字串的一些上下文。
.IP "\fBwrap\fR" 4
.IX Item "wrap"
指示在外觀中是否可以損壞空格的布林值。如果為 true，則字串在使用之前被規範化。
.Sp
此資訊使用 \fBwrap\fR 或 \fBno-wrap\fR 標誌寫入 \s-1PO\s0 檔案。
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
我們應該換行的列 (預設值：76)。
.Sp
此資訊不會寫入 \s-1PO\s0 檔案。
.RE
.RS 4
.RE
.SH "其他功能"
.IX Header "其他功能"
.IP "\fBcount_entries()\fR" 4
.IX Item "count_entries()"
返回目錄中的條目數 (不帶標題)。
.IP "\fBcount_entries_doc()\fR" 4
.IX Item "count_entries_doc()"
返回文件中的條目數。如果一個字串在文件中出現多次，則會對其進行多次計數。
.IP "msgid($)" 4
.IX Item "msgid($)"
返回給定數字的 msgid。
.IP "msgid_doc($)" 4
.IX Item "msgid_doc($)"
返回文件中具有給定位置的 msgid。
.IP "type_doc($)" 4
.IX Item "type_doc($)"
Returns the type of the msgid with the given position in the document. This is probably only useful to gettextization, and it's stored separately from {$msgid}{'type'} because the later location may be overwritten by another type when the \f(CW$msgid\fR is duplicated in the master document.
.IP "\fBget_charset()\fR" 4
.IX Item "get_charset()"
返回 \s-1PO\s0 標頭中指定的字符集。如果沒有設定，則返回 \*(L"\s-1UTF\-8\s0\*(R"。
.IP "set_charset($)" 4
.IX Item "set_charset($)"
這會將 \s-1PO\s0 標頭的字符集設定為其第一個引數中指定的值。如果您從不呼叫此函式(並且沒有讀取具有指定字符集的檔案)，則預設值為 \*(L"\s-1UTF\-8\s0\*(R"。這個值不會改變這個模組的行為，它只是用來填充頭中的欄位，並在 \fBget_charset()\fR 中返回它。
.SH "作者"
.IX Header "作者"
.Vb 2
\& Denis Barbier <barbier@linuxfr.org>
\& Martin Quinson (mquinson#debian.org)
.Ve