" 开头的段落列表。为简单起见，我们假定文档格式良好，即 "
" 标记是唯一存在的标记，并且该标记位于每个段落的最开始。 .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\-\-; ) { \& # Not the first time we see
. \& # Reput the current line in input, \& # and put the built paragraph to output \& $self\->unshiftline($line,$lref); \& \& # Now that the document is formed, translate it: \& # \- Remove the leading tag \& $paragraph =~ s/^
//s; \& \& # \- push to output the leading tag (untranslated) and the \& # rest of the paragraph (translated) \& $self\->pushline( "
"
\& . $self\->translate($paragraph,$pararef)
\& );
\&
\& next PARAGRAPH;
\& } else {
\& # Append to the paragraph
\& $paragraph .= $line;
\& $pararef = $lref unless(length($pararef));
\& }
\&
\& # Reinit the loop
\& ($line,$lref)=$self\->shiftline();
\& }
\& # Did not get a defined line? End of input file.
\& 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\*(Aqt 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\*(Aqt 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
This array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR holds this input document data as an
array of strings with alternating meanings.
* The string \f(CW$textline\fR holding each line of the input text data.
* The string \f(CW\*(C`$filename:$linenum\*(C'\fR holding its location and called as
"reference" (\f(CW\*(C`linenum\*(C'\fR starts with 1).
.Sp
请注意，它不解析任何内容。当您完成将输入文件打包到文档中时，应该使用 \fBparse()\fR 函数。
.IP write($) 4
.IX Item "write($)"
将翻译后的文档写入给定的文件名。
.Sp
This translated document data are provided by:
* \f(CW\*(C`$self\->docheader()\*(C'\fR holding the header text for the plugin, and
* \f(CW\*(C`@{$self\->{TT}{doc_out}}\*(C'\fR holding each line of the main translated text in the array.
.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
\& [normal use of the po4a document...]
\&
\& ($percent,$hit,$queries) = $document\->stats();
\& print "We found translations for $percent\e% ($hit from $queries) of strings.\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 returns the first array item and drop it from the array.
\& * Perl unshift prepends an item to the array as the first array item.
\& * Perl pop returns the last array item and drop it from the array.
\& * Perl push appends an item to the array as the last array item.
.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