.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" 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
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "LOCALE::PO4A::PO.3PM 1"
.TH LOCALE::PO4A::PO.3PM 1 2025-11-22 "perl v5.42.0" "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();
\&
\&    # Read PO file
\&    $pofile\->read(\*(Aqfile.po\*(Aq);
\&
\&    # Add an entry
\&    $pofile\->push(\*(Aqmsgid\*(Aq => \*(AqHello\*(Aq, \*(Aqmsgstr\*(Aq => \*(Aqbonjour\*(Aq,
\&                  \*(Aqflags\*(Aq => "wrap", \*(Aqreference\*(Aq=>\*(Aqfile.c:46\*(Aq);
\&
\&    # Extract a translation
\&    $pofile\->gettext("Hello"); # returns \*(Aqbonjour\*(Aq
\&
\&    # Write back to a file
\&    $pofile\->write(\*(Aqotherfile.po\*(Aq);
.Ve
.SH 描述
.IX Header "描述"
Locale::Po4a::Po 是一个允许您操作消息目录的模块。您可以从/向文件 (其扩展名通常是 \fIpo\fR)
加载和写入，您可以动态构建新条目或请求字符串翻译。
.PP
有关 PO 格式的消息目录及其使用的更完整说明，请参阅 gettext 程序(节点"\*(AqPO 文件"\*(Aq)的信息文档。
.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
\&    [some use of the PO file to translate stuff]
\&
\&    ($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 行的 \*(Aqfile.c\*(Aq 中)。它可以是空格分隔列表，以防发生多次。
.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\*(Aqs stored separately from
{$msgid}{\*(Aqtype\*(Aq} 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 <barbier@linuxfr.org>
\& Martin Quinson (mquinson#debian.org)
.Ve
.SH 翻译
.IX Header "翻译"
taotieren <admin@taotieren.com>