
        *****************************************************
        *           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();

    # Read PO file
    $pofile->read('file.po');

    # Add an entry
    $pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
                  'flags' => "wrap", 'reference'=>'file.c:46');

    # Extract a translation
    $pofile->gettext("Hello"); # returns 'bonjour'

    # Write back to a file
    $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 报告文件的状态。使用示例：

    [some use of the PO file to translate stuff]

    ($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)

=head1 翻译

taotieren <admin@taotieren.com>

