" 开头的段落列表。为简单起见，我们假定文档格式良好，即 "
" 标记是唯一存在的标记，并且该标记位于每个段落的最开始。 .PP .Vb 2 \& sub parse { \& my $self = shift; \& \& PARAGRAPH: while (1) { \& my ($paragraph,$pararef)=("",""); \& my $first=1; \& my ($line,$lref)=$self\->shiftline(); \& while (defined($line)) { \& if ($line =~ m/
/ && !$first\-\-; ) { \& # 这不是我们第一次看到
。 \& # 将当前行重新放入输入， \& # 并将构建的段落输出 \& $self\->unshiftline($line,$lref); \& \& # 现在文档已形成，请翻译它： \& # \- 删除前导标记 \& $paragraph =~ s/^
//s; \& \& # \- 按键输出前导标签(未翻译)和 \& # 段落的其余部分(已翻译) \& $self\->pushline( "
"
\& . $self\->translate($paragraph,$pararef)
\& );
\&
\& next PARAGRAPH;
\& } else {
\& # 追加到段落后面
\& $paragraph .= $line;
\& $pararef = $lref unless(length($pararef));
\& }
\&
\& # 重新初始化循环
\& ($line,$lref)=$self\->shiftline();
\& }
\& # 没有得到定义的行吗？输入文件的结尾。
\& return;
\& }
\& }
.Ve
.PP
一旦实现了解析函数，就可以使用下一节中介绍的公共接口来使用 document 类。
.SH 使用解析器的脚本的公共接口
.IX Header "使用解析器的脚本的公共接口"
.SS "构造 函数"
.IX Subsection "构造 函数"
.IP process(%) 4
.IX Item "process(%)"
此函数可以在一次调用中完成处理 po4a 文档所需的所有操作。它的参数必须打包为散列。操作：
.RS 4
.IP a. 3
.IX Item "a."
读取 po_in_name 中指定的所有 PO 文件
.IP b. 3
.IX Item "b."
读取在 file_in_name 中指定的所有原始文档
.IP c. 3
.IX Item "c."
解析文档
.IP d. 3
.IX Item "d."
读取并应用所有指定的附录
.IP e. 3
.IX Item "e."
将翻译的文档写入 file_out_name (如果给定)
.IP f. 3
.IX Item "f."
将提取的 PO 文件写入 po_out_name (如果给定)
.RE
.RS 4
.Sp
参数，除了 \fBnew()\fR 接受的参数(具有预期类型)：
.IP "file_in_name (@)" 4
.IX Item "file_in_name (@)"
我们应该在其中读取输入文档的文件名列表。
.IP "file_in_charset ($)" 4
.IX Item "file_in_charset ($)"
Charset used in the input document (if it isn't specified, use UTF\-8).
.IP "file_out_name ($)" 4
.IX Item "file_out_name ($)"
我们应该在其中写入输出文档的文件名。
.IP "file_out_charset ($)" 4
.IX Item "file_out_charset ($)"
Charset used in the output document (if it isn't specified, use UTF\-8).
.IP "po_in_name (@)" 4
.IX Item "po_in_name (@)"
我们应该从中读取输入 PO 文件的文件名列表，其中包含将用于翻译文档的翻译。
.IP "po_out_name ($)" 4
.IX Item "po_out_name ($)"
我们应该在其中写入输出 PO 文件的文件名，其中包含从输入文档提取的字符串。
.IP "addendum (@)" 4
.IX Item "addendum (@)"
我们应该从中读取附录的文件名列表。
.IP "addendum_charset ($)" 4
.IX Item "addendum_charset ($)"
附录的字符集。
.RE
.RS 4
.RE
.IP new(%) 4
.IX Item "new(%)"
创建新的 po4a 文档。接受的选项 (在作为参数传递的哈希中)：
.RS 4
.IP "verbose ($)" 4
.IX Item "verbose ($)"
设置详细程度。
.IP "debug ($)" 4
.IX Item "debug ($)"
设置调试。
.IP "wrapcol ($)" 4
.IX Item "wrapcol ($)"
The column at which we should wrap text in output document (default: 76).
.Sp
The negative value means not to wrap lines at all.
.RE
.RS 4
.Sp
Also it accepts next options for underlying Po-files: \fBporefs\fR, \fBcopyright-holder\fR, \fBmsgid-bugs-address\fR, \fBpackage-name\fR, \fBpackage-version\fR, \fBwrap-po\fR.
.RE
.SS 操作文档文件
.IX Subsection "操作文档文件"
.IP read($$$) 4
.IX Item "read($$$)"
Add another input document data at the end of the existing array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR.
.Sp
This function takes two mandatory arguments and an optional one.
* The filename to read on disk;
* The name to use as filename when building the reference in the PO file;
* The charset to use to read that file (UTF\-8 by default)
.Sp
此数组 \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR 将此输入文档数据保存为。
具有交替含义的字符串数组。
*字符串 \f(CW$textline\fR 保存输入文本数据的每一行。
*字符串 \f(CW\*(C`$filename:$linenum\*(C'\fR 保存其位置并调用为。
"reference" (\f(CW\*(C`linenum\*(C'\fR 从 1 开始)。
.Sp
请注意，它不解析任何内容。当您完成将输入文件打包到文档中时，应该使用 \fBparse()\fR 函数。
.IP write($) 4
.IX Item "write($)"
将翻译后的文档写入给定的文件名。
.Sp
此翻译文档数据由以下人员提供：
* \f(CW\*(C`$self\->docheader()\*(C'\fR 保存插件的标题文本，以及。
* \f(CW\*(C`@{$self\->{TT}{doc_out}}\*(C'\fR 保存数组中主翻译文本的每一行。
.SS "操作 PO 文件"
.IX Subsection "操作 PO 文件"
.IP readpo($) 4
.IX Item "readpo($)"
将文件的内容（该名称作为参数传递）添加到现有输入 PO。旧内容不会丢弃。
.IP writepo($) 4
.IX Item "writepo($)"
将提取的 PO 文件写入给定的文件名。
.IP \fBstats()\fR 4
.IX Item "stats()"
返回到目前为止完成的转换的一些统计信息。请注意，它与 msgfmt \-\-statistic 打印的统计数据不同。在这里，它是关于 PO 文件最近使用情况的统计信息，而 msgfmt 则报告该文件的状态。它是应用于输入 PO 文件的 Locale::Po4a::Po::stats_get 函数的封装。使用示例：
.Sp
.Vb 1
\& [正常使用 po4a 文档...]
\&
\& ($percent,$hit,$queries) = $document\->stats();
\& print "我们找到了 $percent\e% ($hit from $queries) 字符串的翻译\en";
.Ve
.SS 操作附录
.IX Subsection "操作附录"
.IP addendum($) 4
.IX Item "addendum($)"
请参阅 \fBpo4a\fR\|(7)，了解有关附录的详细信息，以及翻译人员应如何编写附录。要对翻译后的文档应用附录，只需将其文件名传递给此函数，即可完成 ;)
.Sp
此函数在出错时返回非空整数。
.SH 用于编写派生解析器的内部函数
.IX Header "用于编写派生解析器的内部函数"
.SS 获取输入，提供输出
.IX Subsection "获取输入，提供输出"
提供了四个函数来获取输入和返回输出。它们与 Perl 的 shift/unshift 和 push/pop 非常相似。
.PP
.Vb 4
\& * Perl shift 返回第一个数组项并将其从数组中删除。
\& * Perl unshift 将项作为第一个数组项添加到数组中。
\& * Perl pop 返回最后一个数组项并将其从数组中删除。
\& * Perl push 将一项作为最后一个数组项追加到数组中。
.Ve
.PP
第一对是关于输入的，第二对是关于输出的。助记符：在 input 中，您感兴趣的是第一行，shift 提供什么，而在 output 中，您希望将结果添加到末尾，就像 push 一样。
.IP \fBshiftline()\fR 4
.IX Item "shiftline()"
此函数从数组 \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR 返回要解析的第一行及其对应的引用 (打包为数组)，并删除前两个数组项。这里，引用由字符串 \f(CW\*(C`$filename:$linenum\*(C'\fR 提供。
.IP unshiftline($$) 4
.IX Item "unshiftline($$)"
取消将输入文档的最后移位行及其对应的引用移回 \f(CW\*(C`{$self\->{TT}{doc_in}}\*(C'\fR 的头部。
.IP pushline($) 4
.IX Item "pushline($)"
将新行推到 \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR 的末尾。
.IP \fBpopline()\fR 4
.IX Item "popline()"
从 \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR 的末尾弹出最后推送的行。
.SS 将字符串标记为可翻译
.IX Subsection "将字符串标记为可翻译"
提供一个函数来处理应该翻译的文本。
.IP translate($$$) 4
.IX Item "translate($$$)"
必选参数：
.RS 4
.IP \- 2
要翻译的字符串
.IP \- 2
此字符串的引用 (即输入文件中的位置)
.IP \- 2
此字符串的类型(即对其结构角色的文本描述；在 \fBLocale::Po4a::Po::gettextization()\fR 中使用；另请参阅 \fBpo4a\fR\|(7)，\fBGettextization: how does it work?\fR 部分)
.RE
.RS 4
.Sp
此函数还可以接受一些额外的参数。它们必须组织为散列。例如：
.Sp
.Vb 2
\& $self\->translate("string","ref","type",
\& \*(Aqwrap\*(Aq => 1);
.Ve
.IP \fBwrap\fR 4
.IX Item "wrap"
指示我们是否可以认为字符串中的空格不重要的布尔值。如果是，则该函数在查找或提取翻译之前对字符串进行规范化，并对翻译进行封装。
.IP \fBwrapcol\fR 4
.IX Item "wrapcol"
the column at which we should wrap (default: the value of \fBwrapcol\fR specified during creation of the TransTractor or 76).
.Sp
The negative value will be substracted from the default.
.IP \fBcomment\fR 4
.IX Item "comment"
要添加到条目的额外注释。
.RE
.RS 4
.Sp
操作：
.IP \- 2
将字符串、引用和类型推送到 po_out。
.IP \- 2
返回字符串的翻译(如 po_in 中所示)，以便解析器可以构建 doc_out。
.IP \- 2
在将字符串发送到 po_out 和返回翻译之前，处理字符集以重新编码字符串。
.RE
.RS 4
.RE
.SS 其他函数
.IX Subsection "其他函数"
.IP \fBverbose()\fR 4
.IX Item "verbose()"
返回是否在创建翻译提取器期间传递了 verbose 选项。
.IP \fBdebug()\fR 4
.IX Item "debug()"
返回是否在创建翻译提取器期间传递了调试选项。
.IP \fBget_in_charset()\fR 4
.IX Item "get_in_charset()"
This function return the charset that was provided as master charset
.IP \fBget_out_charset()\fR 4
.IX Item "get_out_charset()"
此函数将返回应该在输出文档中使用的字符集(通常用于替换已找到的输入文档的检测到的字符集)。
.Sp
它将使用命令行中指定的输出字符集。如果未指定该命令，则将使用输入 PO 的字符集，如果输入 PO 具有默认的 "CHARSET"，则返回输入文档的字符集，以便不会执行编码。
.SH 未来方向
.IX Header "未来方向"
当前翻译提取器的一个缺点是它不能处理包含所有语言的翻译文档，如 debconf 模板或 .desktop 文件。
.PP
要解决此问题，只需更改接口：
.IP \- 2
将散列作为 po_in_name (每种语言的列表)
.IP \- 2
添加要翻译的参数以指示目标语言
.IP \- 2
使用类似映射的语法创建一个 pushline_all 函数，该函数将为所有语言创建其内容的 pushline：
.Sp
.Vb 3
\& $self\->pushline_all({ "Description[".$langcode."]=".
\& $self\->translate($line,$ref,$langcode)
\& });
.Ve
.PP
看看是否足够 ;)
.SH 作者
.IX Header "作者"
.Vb 3
\& Denis Barbier