
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 名稱

Locale::Po4a::Po - PO 檔案操作模組

=head1 簡介

    use Locale::Po4a::Po;
    my $pofile=Locale::Po4a::Po->new();

    # 讀取 PO 檔案
    $pofile->read('file.po');

    # 新增條目
    $pofile->push('msgid' => 'Hello', 'msgstr' => '你好',
                  'flags' => "wrap", 'reference'=>'file.c:46');

    # 提取翻譯
    $pofile->gettext("Hello"); # 返回 'bonjour'

    # 寫回檔案
    $pofile->write('otherfile.po');

=head1 描述

Locale::Po4a::Po 是一個允許您操作訊息目錄的模組。您可以從/向檔案 (其副檔名通常是 I<po>) 載入和寫入，您可以動態構建新條目或請求字串翻譯。

有關 PO 格式的訊息目錄及其使用的更完整說明，請參閱 gettext 程式(節點"'PO 文件"')的資訊文件。

此模組是 po4a 專案的一部分，該專案的目標是使用 PO 檔案(在原始位置設計用於簡化程式訊息的翻譯)來翻譯所有內容，包括文件(手冊頁、資訊手冊)、軟體包說明、debconf 模板以及可能從中受益的所有內容。

=head1 此模組接受的選項

=over 4

=item B<--porefs> I<type>

指定引用格式。引數 I<type> 可以是以下值之一：B<never> 不生成任何引用；B<file> 只指定不帶行號的檔案；B<counter> 用遞增的計數器替換行號；B<full> 包含完整引用（預設值：full）。

=item B<--wrap-po> B<no>|B<newlines>|I<number> (default: 76)

指定應如何封裝 po 檔案。這使我們可以選擇封裝良好但可能導致 git 衝突的檔案，或者更容易自動處理但對人類來說更難讀取的檔案。

從歷史上看，gettext 套件已經重新格式化了第 77 列化妝品的 po 檔案。此選項指定 po4a 的行為。如果設定為數值，po4a 將在內容中的此列和換行之後封裝 po 檔案。如果設定為 B<newlines>，po4a 將只在內容中的新行之後拆分 msgid 和 msgstr。如果設置為 B<no>，則 po4a 根本不會封裝 po 檔案。引用註釋總是由我們在內部使用的 gettext 工具封裝。

請注意，此選項對 msgid 和 msgstr 的封裝方式（即，將換行符新增到這些字串的內容中）沒有影響。

=item B<--msgid-bugs-address> I<email@address>

設定 msgid 錯誤的報告地址。 預設情況下，建立的 POT 檔案沒有 Report-Msgid-Bugs-To 欄位。

=item B<--copyright-holder> I<string>

在 POT 標頭中設定版權所有者。 預設值為“自由軟體基金會有限公司。”

=item B<--package-name> I<string>

設定 POT 標頭的程式包名稱。 預設值為“封裝”。

=item B<--package-version> I<string>

設定 POT 標頭的軟體包版本。 預設值為“版本”。

=back

=head1 有關整個訊息目錄的函式

=over 4

=item new()

建立新的訊息目錄。如果提供了引數，則它是我們應該載入的 PO 檔案的名稱。

=item read($)

讀取 PO 檔案(其名稱作為引數給定)。self 中以前存在的條目不會刪除，新條目會新增到目錄的末尾。

=item write($)

將當前目錄寫入給定檔案。

=item write_if_needed($$)

與 write 類似，但如果 PO 或 POT 檔案已經存在，則物件將被寫入臨時檔案中，該臨時檔案將與現有檔案進行比較，以檢查是否需要更新 (這避免了僅僅為了更新線參考或 POT-Creation-Date 欄位而更改 POT)。

=item filter($)

此函式用於從現有目錄中提取目錄。只有在給定檔案中有引用的條目才會放入結果目錄中。

該函式解析其引數，將其轉換為 Perl 函式定義，計算該定義的值，並篩選該函式返回 true 的欄位。

我有時喜歡 Perl ;)

=back

=head1 使用訊息目錄進行翻譯的函式

=over 4

=item gettext($%)

請求翻譯當前目錄中作為引數給定的字串。如果未找到原始 (未翻譯) 字串，該函數將返回該字串。

在要轉換的字串之後，可以傳遞一組額外的引數。以下是有效的條目：

=over 

=item B<wrap>

指示我們是否可以認為字串中的空格不重要的布林值。如果是，則該函式在查詢翻譯之前對字串進行規範化，並對結果進行封裝。

=item B<wrapcol>

我們應該換行的列 (預設值：76)。

=back

=item stats_get()

返回自上次呼叫 stats_clear() 以來 gettext 命中率的統計資訊。請注意，它與 msgfmt --statistic 列印的統計資料不同。這裡，它是關於 PO 檔案最近使用情況的統計資訊，而 msgfmt 報告檔案的狀態。使用示例：

    [使用 PO 檔案翻譯內容]

    ($percent,$hit,$queries) = $pofile->stats_get();
    print "So far, we found translations for $percent\%  ($hit of $queries) of strings.\n";

=item stats_clear()

清除有關 gettext 命中的統計資訊。

=back

=head1 用於構建訊息目錄的函式

=over 4

=item push(%)

在當前目錄的末尾推送新條目。引數應形成雜湊表。有效金鑰為：

=over 4

=item B<msgid>

原始語言的字串。

=item B<msgstr>

翻譯。

=item B<reference>

指示找到此字串的地點。示例：file.c:46(意思是在第 46 行的 'file.c' 中)。它可以是空格分隔列表，以防發生多次。

=item B<comment>

此處手動新增的評論（由翻譯人員）。此處的格式是免費的。

=item B<automatic>

由字串提取程式自動新增的註釋。有關詳細資訊，請參閱 B<--add-comments> 程式的 B<xgettext> 選項。

=item B<flags>

此條目的所有已定義標誌的以空格分隔的列表。

有效標誌為： B<c-text>, B<python-text>, B<lisp-text>, B<elisp-text>, B<librep-text>, B<smalltalk-text>, B<java-text>, B<awk-text>, B<object-pascal-text>, B<ycp-text>, B<tcl-text>, B<wrap>, B<no-wrap> 和 B<fuzzy>.

有關它們的含義，請參閱 gettext 文件。

=item B<type>

這主要是一個內部引數：它是在對文件進行獲取文字化時使用的。這裡的想法是將原始和翻譯都解析成 PO 物件，並將它們合併，使用一個的 msgid 作為 msgid，使用另一個的 msgid 作為 msgstr。為了確保一切正常，PO 物件中的每個 msgid 都根據它們的結構 (就像 DocBook 中的 "chapt"、"sect1"、"p" 等)被賦予一個型別。如果字元串型別不同，則意味著兩個檔案不共享相同的結構，並且該過程會報告錯誤。

此資訊在 PO 檔案中作為自動註釋寫入，因為這為翻譯人員提供了有關要翻譯的字串的一些上下文。

=item B<wrap>

指示在外觀中是否可以損壞空格的布林值。如果為 true，則字串在使用之前被規範化。

此資訊使用 B<wrap> 或 B<no-wrap> 標誌寫入 PO 檔案。

=item B<wrapcol>

ignored; the key is kept for backward computability.

=back

=back

=head1 其他功能

=over 4

=item count_entries()

返回目錄中的條目數 (不帶標題)。

=item count_entries_doc()

返回文件中的條目數。如果一個字串在文件中出現多次，則會對其進行多次計數。

=item msgid($)

返回給定數字的 msgid。

=item msgid_doc($)

返回文件中具有給定位置的 msgid。

=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 $msgid is duplicated in the master document.

=item get_charset()

返回 PO 標頭中指定的字符集。如果沒有設定，則返回 "UTF-8"。

=back

=head1 作者

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)

