.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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 1" .TH LOCALE::PO4A::PO.3PM 1 2024-06-26 "perl v5.38.2" "User Contributed Perl Documentation" .\" 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 \- PO 檔案操作模組 .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 有關 PO 格式的訊息目錄及其使用的更完整說明,請參閱 gettext 程式(節點"'PO 文件"')的資訊文件。 .PP 此模組是 po4a 專案的一部分,該專案的目標是使用 PO 檔案(在原始位置設計用於簡化程式訊息的翻譯)來翻譯所有內容,包括文件(手冊頁、資訊手冊)、軟體包說明、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 錯誤的報告地址。 預設情況下,建立的 POT 檔案沒有 Report-Msgid-Bugs-To 欄位。 .IP "\fB\-\-copyright\-holder\fR \fIstring\fR" 4 .IX Item "--copyright-holder string" 在 POT 標頭中設定版權所有者。 預設值為“自由軟體基金會有限公司。” .IP "\fB\-\-package\-name\fR \fIstring\fR" 4 .IX Item "--package-name string" 設定 POT 標頭的程式包名稱。 預設值為“封裝”。 .IP "\fB\-\-package\-version\fR \fIstring\fR" 4 .IX Item "--package-version string" 設定 POT 標頭的軟體包版本。 預設值為“版本”。 .SH 有關整個訊息目錄的函式 .IX Header "有關整個訊息目錄的函式" .IP \fBnew()\fR 4 .IX Item "new()" 建立新的訊息目錄。如果提供了引數,則它是我們應該載入的 PO 檔案的名稱。 .IP read($) 4 .IX Item "read($)" 讀取 PO 檔案(其名稱作為引數給定)。self 中以前存在的條目不會刪除,新條目會新增到目錄的末尾。 .IP write($) 4 .IX Item "write($)" 將當前目錄寫入給定檔案。 .IP write_if_needed($$) 4 .IX Item "write_if_needed($$)" 與 write 類似,但如果 PO 或 POT 檔案已經存在,則物件將被寫入臨時檔案中,該臨時檔案將與現有檔案進行比較,以檢查是否需要更新 (這避免了僅僅為了更新線參考或 POT-Creation-Date 欄位而更改 POT)。 .IP filter($) 4 .IX Item "filter($)" 此函式用於從現有目錄中提取目錄。只有在給定檔案中有引用的條目才會放入結果目錄中。 .Sp 該函式解析其引數,將其轉換為 Perl 函式定義,計算該定義的值,並篩選該函式返回 true 的欄位。 .Sp 我有時喜歡 Perl ;) .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 列印的統計資料不同。這裡,它是關於 PO 檔案最近使用情況的統計資訊,而 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" 這主要是一個內部引數:它是在對文件進行獲取文字化時使用的。這裡的想法是將原始和翻譯都解析成 PO 物件,並將它們合併,使用一個的 msgid 作為 msgid,使用另一個的 msgid 作為 msgstr。為了確保一切正常,PO 物件中的每個 msgid 都根據它們的結構 (就像 DocBook 中的 "chapt"、"sect1"、"p" 等)被賦予一個型別。如果字元串型別不同,則意味著兩個檔案不共享相同的結構,並且該過程會報告錯誤。 .Sp 此資訊在 PO 檔案中作為自動註釋寫入,因為這為翻譯人員提供了有關要翻譯的字串的一些上下文。 .IP \fBwrap\fR 4 .IX Item "wrap" 指示在外觀中是否可以損壞空格的布林值。如果為 true,則字串在使用之前被規範化。 .Sp 此資訊使用 \fBwrap\fR 或 \fBno-wrap\fR 標誌寫入 PO 檔案。 .IP \fBwrapcol\fR 4 .IX Item "wrapcol" ignored; the key is kept for backward computability. .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()" 返回 PO 標頭中指定的字符集。如果沒有設定,則返回 "UTF\-8"。 .SH 作者 .IX Header "作者" .Vb 2 \& Denis Barbier \& Martin Quinson (mquinson#debian.org) .Ve