Locale::Po4a::Po(3pm) Po4a 工具 Locale::Po4a::Po(3pm)

名称

Locale::Po4a::Po - PO 文件操作模块

简介

    use Locale::Po4a::Po;
    my $pofile=Locale::Po4a::Po->new();
    # 读取 PO 文件
    $pofile->read('file.po');
    # 添加条目
    $pofile->push('msgid' => 'Hello', 'msgstr' => '你好',
                  'flags' => "wrap", 'reference'=>'file.c:46');
    # 提取翻译
    $pofile->gettext("Hello"); # 返回 'bonjour'
    # 写回文件
    $pofile->write('otherfile.po');

描述

Locale::Po4a::Po 是一个允许您操作消息目录的模块。您可以从/向文件 (其扩展名通常是 po) 加载和写入，您可以动态构建新条目或请求字符串翻译。

有关 PO 格式的消息目录及其使用的更完整说明，请参阅 gettext 程序(节点"'PO 文件"')的信息文档。

此模块是 po4a 项目的一部分，该项目的目标是使用 PO 文件(在原始位置设计用于简化程序消息的翻译)来翻译所有内容，包括文档(手册页、信息手册)、软件包说明、debconf 模板以及可能从中受益的所有内容。

此模块接受的选项

指定引用格式。参数 type 可以是以下值之一：never 不生成任何引用；file 只指定不带行号的文件；counter 用递增的计数器替换行号；full 包含完整引用（默认值：full）。
指定应如何封装 po 文件。这使我们可以选择封装良好但可能导致 git 冲突的文件，或者更容易自动处理但对人类来说更难读取的文件。

从历史上看，gettext 套件已经重新格式化了第 77 列化妆品的 po 文件。此选项指定 po4a 的行为。如果设置为数值，po4a 将在内容中的此列和换行之后封装 po 文件。如果设置为 newlines，po4a 将只在内容中的新行之后拆分 msgid 和 msgstr。如果设置为 no，则 po4a 根本不会封装 po 文件。引用注释总是由我们在内部使用的 gettext 工具封装。

请注意，此选项对 msgid 和 msgstr 的封装方式（即，将换行符添加到这些字符串的内容中）没有影响。

设置 msgid 错误的报告地址。 默认情况下，创建的 POT 文件没有 Report-Msgid-Bugs-To 字段。
在 POT 标头中设置版权所有者。 默认值为“自由软件基金会有限公司。”
设置 POT 标头的程序包名称。 默认值为“封装”。
设置 POT 标头的软件包版本。 默认值为“版本”。

有关整个消息目录的函数

创建新的消息目录。如果提供了参数，则它是我们应该加载的 PO 文件的名称。
读取 PO 文件(其名称作为参数给定)。self 中以前存在的条目不会删除，新条目会添加到目录的末尾。
将当前目录写入给定文件。
与 write 类似，但如果 PO 或 POT 文件已经存在，则对象将被写入临时文件中，该临时文件将与现有文件进行比较，以检查是否需要更新 (这避免了仅仅为了更新线参考或 POT-Creation-Date 字段而更改 POT)。
此函数用于从现有目录中提取目录。只有在给定文件中有引用的条目才会放入结果目录中。

该函数解析其参数，将其转换为 Perl 函数定义，计算该定义的值，并筛选该函数返回 true 的字段。

我有时喜欢 Perl ;)

重新编码为UTF-8 PO的消息。如果 PO 文件中没有指定字符集 ("CHARSET" 值)，或者它已经是 UTF-8 或 ASCII，则不执行任何操作。

使用消息目录进行翻译的函数

请求翻译当前目录中作为参数给定的字符串。如果未找到原始 (未翻译) 字符串，该函数将返回该字符串。

在要转换的字符串之后，可以传递一组额外的参数。以下是有效的条目：

指示我们是否可以认为字符串中的空格不重要的布尔值。如果是，则该函数在查找翻译之前对字符串进行规范化，并对结果进行封装。
我们应该换行的列 (默认值：76)。
返回自上次调用 stats_clear() 以来 gettext 命中率的统计信息。请注意，它与 msgfmt --statistic 打印的统计数据不同。这里，它是关于 PO 文件最近使用情况的统计信息，而 msgfmt 报告文件的状态。使用示例： 

    [使用 PO 文件翻译内容]
    ($percent,$hit,$queries) = $pofile->stats_get();
    print "So far, we found translations for $percent\%  ($hit of $queries) of strings.\n";
清除有关 gettext 命中的统计信息。

用于构建消息目录的函数

在当前目录的末尾推送新条目。参数应形成哈希表。有效密钥为：
原始语言的字符串。
翻译。
指示找到此字符串的地点。示例：file.c:46(意思是在第 46 行的 'file.c' 中)。它可以是空格分隔列表，以防发生多次。
此处手动添加的评论（由翻译人员）。此处的格式是免费的。
由字符串提取程序自动添加的注释。有关详细信息，请参阅 --add-comments 程序的 xgettext 选项。
此条目的所有已定义标志的以空格分隔的列表。

有效标志为： c-text, python-text, lisp-text, elisp-text, librep-text, smalltalk-text, java-text, awk-text, object-pascal-text, ycp-text, tcl-text, wrap, no-wrap 和 fuzzy.

有关它们的含义，请参阅 gettext 文档。

这主要是一个内部参数：它是在对文档进行获取文本化时使用的。这里的想法是将原始和翻译都解析成 PO 对象，并将它们合并，使用一个的 msgid 作为 msgid，使用另一个的 msgid 作为 msgstr。为了确保一切正常，PO 对象中的每个 msgid 都根据它们的结构 (就像 DocBook 中的 "chapt"、"sect1"、"p" 等)被赋予一个类型。如果字符串类型不同，则意味着两个文件不共享相同的结构，并且该过程会报告错误。

此信息在 PO 文件中作为自动注释写入，因为这为翻译人员提供了有关要翻译的字符串的一些上下文。

指示在外观中是否可以损坏空格的布尔值。如果为 true，则字符串在使用之前被规范化。

此信息使用 wrap 或 no-wrap 标志写入 PO 文件。

我们应该换行的列 (默认值：76)。

此信息不会写入 PO 文件。

其他功能

返回目录中的条目数 (不带标题)。
返回文档中的条目数。如果一个字符串在文档中出现多次，则会对其进行多次计数。
返回给定数字的 msgid。
返回文档中具有给定位置的 msgid。
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.
返回 PO 标头中指定的字符集。如果没有设置，则返回 "UTF-8"。
这会将 PO 标头的字符集设置为其第一个参数中指定的值。如果您从不调用此函数(并且没有读取具有指定字符集的文件)，则默认值为 "UTF-8"。这个值不会改变这个模块的行为，它只是用来填充头中的字段，并在 get_charset() 中返回它。

作者

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)
2023-01-03 Po4a 工具