Provided by: po4a_0.67-2_all 
名称
Locale::Po4a::Xml - 将 XML 文档和衍生内容从/转换为 PO 文件
描述
Po4a (PO For Anything) 项目的目标是在文档等不需要翻译的领域使用 gettext 工具简化翻译(更有
趣的是，简化翻译的维护)。
Locale::Po4a::Xml 是一个帮助将 XML 文档翻译成其他 [人类] 语言的模块。它还可以用作为基于
XML 的文档构建模块的基础。
使用 PO4A::XML 进行转换
此模块可直接用于处理通用 XML 文档。这将提取所有标记的内容，而不提取属性，因为它是大多数基
于 XML 的文档中的文本写入位置。
有一些选项 (将在下一节中介绍) 可以自定义此行为。如果这不适合您的文档格式，则鼓励您编写由此
衍生的您自己的模块，以描述您的格式的详细信息。有关过程描述，请参阅下面的 WRITING DERIVATE
MODULES 小节。
此模块接受的选项
全局调试选项会导致此模块显示排除的字符串，以查看它是否跳过了重要内容。
以下是此模块的特定选项：
nostrip
防止它剥离提取字符串周围的空格。
wrap
考虑到空格并不重要，规范化要翻译的字符串，并对翻译后的文档进行换行。自定义标记选项可以
覆盖此选项。请参阅下面的 translated 选项。
unwrap_attributes
默认情况下，属性是换行的。此选项禁用换行。
caseinsensitive
它使标签和属性搜索以不区分大小写的方式工作。如果定义了它，它会将 <BooK>laNG 和
<BOOK>Lang 视为 <book>lang。
escapequotes
输出字符串中的转义引号。例如，创建供 Android 构建工具使用的字符串资源时是必需的。
另请参阅：https://developer.android.com/guide/topics/resources/string-resource.html
includeexternal
定义后，外部实体将包括在生成的 (翻译的) 文档中，并用于提取字符串。如果未定义，则必须将
外部实体单独转换为独立文档。
ontagerror
此选项定义模块遇到无效 XML 语法 (结束标记与最后一个开始标记不匹配) 时的行为。它可以采
用以下值：
fail
这是默认值。模块将退出，并出现错误。
warn
该模块将继续运行，并发出警告。
silent
模块将继续，没有任何警告。
使用此选项时要小心。通常建议修复输入文件。
tagsonly
注意：此选项已弃用。
仅提取 tags 选项中指定的标记。否则，它将提取除指定标记之外的所有标记。
doctype
尝试与文档的 doctype 的第一行匹配的字符串(如果已定义)。如果不是，则会出现一条警告，指
示该文档的类型可能不正确。
addlang
指示标记的路径 (例如，<bbb><aaa>) 的字符串，其中 lang="..." 需要增加属性。语言将定义为
PO 文件的基本名称，不带任何 .po 扩展名。
optionalclosingtag
指示关闭标记是否可选的布尔值（如 HTML 中所示）。默认情况下，缺少的关闭标记会引发根据
ontagerror 处理的错误。
tags
注意：此选项已弃用。您应该改用 translated 和 untranslated 选项。
要翻译或跳过的以空格分隔的标签列表。默认情况下，将排除指定的标记，但如果使用
"tagsonly" 选项，则只包含指定的标记。标记的格式必须是 <aaa>，但是您可以加入一些
(<bbb><aaa>)，说明标记 <aaa> 的内容只有在转换为 <bbb> 标记时才会被转换。
您还可以通过在标签层次结构前面放置一些字符来指定一些标签选项。例如，您可以放入 'W' (换
行) 或 'W' (不换行) 来覆盖全局 wrap 选项指定的默认行为。
例如：W<chapter><title>
attributes
要转换的标记属性的空格分隔列表。您可以按名称指定属性 (例如，"lang")，但可以在其前面加
上标记层次结构，以指定此属性仅在其位于指定的标记中时才会被转换。例如：<bbb><aaa>lang
指定只有当 lang 属性在 <aaa> 标记中，并且它在 <bbb> 标记中时，lang 属性才会被转换。
foldattributes
不要转换行内标签中的属性。相反，将标记的所有属性替换为 po4a-id=<id>。
当属性不应该被翻译时，这很有用，因为这简化了翻译人员的字符串，并避免了打字错误。
customtag
不应视为标记的以空格分隔的标记列表。这些标记被视为内联标记，不需要关闭。
break
空格分隔的应中断序列的标记列表。默认情况下，所有标签都会打破顺序。
标记的形式必须为 <aaa>，但如果标记 (<aaa>) 仅在另一个标记 (<bbb>) 内时才应考虑，则可以
联接一些 (<bbb><aaa>)。
请注意，标记只能在 break、inline 、placeholder 或 customtag 设置字符串之一中列出。
inline
应视为内联的以空格分隔的标记列表。默认情况下，所有标签都会打破顺序。
标记的形式必须为 <aaa>，但如果标记 (<aaa>) 仅在另一个标记 (<bbb>) 内时才应考虑，则可以
联接一些 (<bbb><aaa>)。
placeholder
应视为占位符的以空格分隔的标记列表。占位符不会打乱顺序，但会单独转换占位符的内容。
占位符在其块中的位置将使用类似于以下内容的字符串进行标记：
<placeholder type=\"footnote\" id=\"0\"/>
标记的形式必须为 <aaa>，但如果标记 (<aaa>) 仅在另一个标记 (<bbb>) 内时才应考虑，则可以
联接一些 (<bbb><aaa>)。
break-pi
默认情况下，处理指令(即 "<? ... ?>" 标记)作为内联标记处理。如果希望将 PI 作为中断标记
处理，请通过此选项。请注意，解析器将未处理的 PHP 标记作为处理指令进行处理。
nodefault
默认情况下，模块不应尝试在任何类别中设置的标记的空格分隔列表。
如果您的标记按此模块的子类具有其默认设置，但您想要设置替代设置，则需要将该标记作为
nodefault 设置字符串的一部分列出。
cpp 支持 C 预处理器指令。设置此选项时，po4a 将把预处理器指令视为段落分隔符。如果必须对 XML
文件进行预处理，这一点很重要，因为否则，如果 po4a 认为它属于当前段落，则指令可能会插入
到行的中间，并且预处理器无法识别它们。注意：预处理器指令只能出现在标记之间 (它们不能换
开标记)。
translated
要翻译的标记的空格分隔列表。
标记的形式必须为 <aaa>，但如果标记 (<aaa>) 仅在另一个标记 (<bbb>) 内时才应考虑，则可以
联接一些 (<bbb><aaa>)。
您还可以通过在标签层次结构前面放置一些字符来指定一些标签选项。这将覆盖全局 wrap 和
defaulttranslateoption 选项指定的默认行为。
w 标签应该被翻译，内容可以重新封装。
W 标签应该被翻译，内容不应该被重新包装。
i 标签应该内联翻译。
p 标记应转换为占位符。
在内部，XML 解析器只关心以下四个选项： w W i p。
* 根据 break 选项，将 Break 中列出的标记设置为 w 或 W 。
* inline 中列出的标记设置为 i。
* placeholder 中列出的标记设置为 p。
* untranslated 中列出的标记未设置任何这些选项。
您可以通过使用 --debug 选项调用 po4a 来验证实际的内部参数行为。
例如：W<chapter><title>
请注意，标签应列在 translated 或 untranslated 设置字符串中。
untranslated
您不想翻译的以空格分隔的标签列表。
标记的形式必须为 <aaa>，但如果标记 (<aaa>) 仅在另一个标记 (<bbb>) 内时才应考虑，则可以
联接一些 (<bbb><aaa>)。
请注意，未翻译标记中的可翻译行内标记将被视为可翻译中断标记，i 设置将被删除，w 或 W 将
根据 wrap 选项进行设置。
defaulttranslateoption
不在任何已翻译、未翻译、分隔符、内联或占位符中的标签的默认类别。
这是 translated 中定义的一组字母，此设置仅对可翻译标记有效。
编写衍生模块
定义要转换的标签和属性
最简单的定制是定义希望解析器转换哪些标记和属性。这应该在 initialize 函数中完成。首先，您应
该调用 main initialize 来获取命令行选项，然后将您的自定义定义附加到选项散列中。如果您想从
命令行处理一些新选项，您应该在调用 main initialize 之前定义它们：
$self->{options}{'new_option'}='';
$self->SUPER::initialize(%options);
$self->{options}{'_default_translated'}.=' <p> <head><title>';
$self->{options}{'attributes'}.=' <p>lang id';
$self->{options}{'_default_inline'}.=' <br>';
$self->treat_options;
您应该在衍生模块中使用 _default_inline, _default_break, _default_placeholder,
_default_translated, _default_untranslated, 和 _default_attributes 选项。这允许用户使用命
令行选项覆盖模块中定义的默认行为。
使用命令行选项覆盖默认行为
如果您不喜欢这个 xml 模块及其派生模块的默认行为，则可以提供命令行选项来更改它们的行为。
请参阅 Locale::Po4a::Docbook(3pm),
覆盖 found_string 功能
另一个简单的步骤是重写函数 "found_string"，该函数接收从解析器中提取的字符串，以便转换它
们。 您可以控制要翻译的字符串，并在转换本身之前或之后执行转换。
它接收提取的文本、关于它所在位置的引用以及包含额外信息的散列，以控制要翻译哪些字符串、如何
翻译它们以及生成注释。
这些选项的内容取决于字符串的类型 (在此散列的条目中指定)：
type="tag"
找到的字符串是可翻译标签的内容。条目 "tag_options" 包含模块 "tags" 选项中标记层次结构
前面的选项字符。
type="attribute"
表示找到的字符串是可翻译属性的值。条目 "attribute" 具有该属性的名称。
它必须返回将替换翻译文档中原始文本的文本。下面是这个函数的一个基本示例：
sub found_string {
my ($self,$text,$ref,$options)=@_;
$text = $self->translate($text,$ref,"type ".$options->{'type'},
'wrap'=>$self->{options}{'wrap'});
return $text;
}
在新的 Dia 模块中还有另一个简单的示例，它只过滤一些字符串。
修改标记类型 (TODO)
这是一个更复杂的方法，但它支持(几乎)完全自定义。它基于散列列表，每个散列定义一种标记类型的
行为。应该对列表进行排序，以便最通用的标记位于最具体的标记之后(首先按开始排序，然后按结束
键排序)。要定义标记类型，您必须使用以下键进行散列：
beginning
在 "<" 之后指定标记的开始。
end 在 ">" 之前指定标记的末尾。
breaking
它会显示这是否是中断标记类。非中断(内联)标签是可以作为另一个标签内容的一部分的标签。它
可以采用值 false (0)、true (1) 或 undefined。如果未定义此标记，则必须定义 f_breaking
函数，该函数将说明该类的具体标记是否为中断标记。
f_breaking
它是一个函数，它将判断下一个标记是否是中断标记。如果 breaking 选项不是，则应该定义它。
f_extract
如果您将此键未定义，泛型提取函数将必须提取标记本身。对于那些可以在它们中拥有其他标记或
特殊结构的标签来说，它很有用，所以主解析器不会错乱。此函数接收一个布尔值，该布尔值表示
如果标记应该从输入流中删除，或者不应该删除。
f_translate
此函数接收标记 (get_string_until() 格式)，并将转换后的标记 (转换后的属性或所有需要的转
换) 作为单个字符串返回。
用于编写派生解析器的内部函数
使用标记
get_path()
此函数返回从文档根到当前标记的路径，格式为 <html><body><p>.
可以作为参数传递额外的标记数组（不带括号）。 这些路径元素将添加到当前路径的末尾。
tag_type()
此函数返回 tag_types 列表中适合输入流中下一个标记的索引，如果它位于输入文件的末尾，则
返回 -1。
这里，标记的结构以 < 开头，以 > 结尾，并且可以包含多行。
这适用于通过 "$self->shiftline()" 和 "$self->unshiftline($$)" 间接保存输入文档数据和引
用的数组 "@{$self->{TT}{doc_in}}"。
extract_tag($$)
此函数返回输入流的下一个标记，而不以数组形式结束，以维护来自输入文件的引用。 它有两个
参数：标记的类型（由 tag_type 返回）和布尔，指示是否应该从输入流中删除标记类型。
这适用于通过 "$self->shiftline()" 和 "$self->unshiftline($$)" 间接保存输入文档数据和引
用的数组 "@{$self->{TT}{doc_in}}"。
get_tag_name(@)
此函数以 extract_tag 返回的数组形式返回作为参数传递的标记名。
breaking_tag()
此函数返回一个布尔值，该布尔值表示输入流中的下一个标记是否为中断标记（内联标记）。 它
保持输入流不变。
treat_tag()
此函数用于转换输入流中的下一个标记。使用每种标签类型的自定义翻译功能。
这适用于通过 "$self->shiftline()" 和 "$self->unshiftline($$)" 间接保存输入文档数据和引
用的数组 "@{$self->{TT}{doc_in}}"。
tag_in_list($@)
此函数返回一个字符串值，表示第一个参数 (标记层次结构) 是否与第二个参数 (标记列表或标记
层次结构) 中的任何标记匹配。如果不匹配，则返回 0。否则，它返回匹配标记的选项(标记前面
的字符)或 1 (如果该标记没有选项)。
使用属性
treat_attributes(@)
此函数处理标记属性的转换。它接收没有开始/结束标记的标记，然后找到属性，并翻译可翻译的
属性(由模块选项 attributes 指定)。这将返回一个带有翻译后的标记的纯字符串。
使用已标记的内容
treat_content()
此函数从输入流获取文本，直到下一个换行标记(不是内联)。使用每种标记类型的自定义翻译功能
对其进行翻译。
这适用于通过 "$self->shiftline()" 和 "$self->unshiftline($$)" 间接保存输入文档数据和引
用的数组 "@{$self->{TT}{doc_in}}"。
使用模块选项
treat_options()
此函数使用模块的选项 (在命令行或 initialize 函数中指定) 填充包含标记、属性和内联数据的
内部结构。
从输入文档获取文本
get_string_until($%)
此函数返回一个数组，该数组包含输入文档中的行（和引用），直到它找到第一个参数。 第二个
参数是选项哈希。值 0 表示已禁用（默认值）和启用 1。
有效选项包括：
include
这使得返回的数组包含搜索的文本
remove
这将从输入中删除返回的流
unquoted
这样可以确保搜索的文本位于任何引号之外
regex
这表示第一个参数是正则表达式，而不是普通字符串
skip_spaces(\@)
此函数接收对段落的引用作为参数(格式由 get_string_until 返回)，跳过其标题空格并将其作为
简单字符串返回。
join_lines(@)
此函数返回一个包含参数数组中文本的简单字符串（丢弃引用）。
此模块的状态
此模块可以翻译标记和属性。
待办事项清单使用PO4A：：XML进行转换
DOCTYPE (ENTITIES)
对实体转换的支持最低。它们是作为整体翻译的，不考虑标签。不支持多行图元，并且在转换过程中始
终重包裹图元。
修改继承模块中的标记类型（在 tag_types 中移动 $self 结构？)
参见
Locale::Po4a::TransTractor(3pm), po4a(7)
作者
Jordi Vilalta <jvprat@gmail.com>
Nicolas François <nicolas.francois@centraliens.net>
版权和许可
版权所有 © 2004 Jordi Vilalta <jvprat@gmail.com>
版权所有 © 2008-2009 Nicolas François <nicolas.francois@centraliens.net>
此程序是自由软件；您可以根据 GPL 条款重新分发和/或修改它(请参阅复制文件)。