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 模板以及可能从中受益的所有内容。

此模块接受的选项

--porefs type
    指定引用格式。参数 type 可以是以下值之一：never 不生成任何引用；file 只指定不带行号的文件；counter 用递增的计数器替换行号；full 包含完整引用（默认值：full）。

--wrap-po no|newlines|number (default: 76)
    指定应如何封装 po 文件。这使我们可以选择封装良好但可能导致 git 冲突的文件，或者更容易自动处理但对人类来说更难读取的文件。

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

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

--msgid-bugs-address email@address
    设置 msgid 错误的报告地址。 默认情况下，创建的 POT 文件没有 Report-Msgid-Bugs-To 字段。

--copyright-holder string
    在 POT 标头中设置版权所有者。 默认值为“自由软件基金会有限公司。”

--package-name string
    设置 POT 标头的程序包名称。 默认值为“封装”。

--package-version string
    设置 POT 标头的软件包版本。 默认值为“版本”。

有关整个消息目录的函数

new()
    创建新的消息目录。如果提供了参数，则它是我们应该加载的 PO 文件的名称。

read($)
    读取 PO 文件(其名称作为参数给定)。self 中以前存在的条目不会删除，新条目会添加到目录的末尾。

write($)
    将当前目录写入给定文件。

write_if_needed($$)
    与 write 类似，但如果 PO 或 POT 文件已经存在，则对象将被写入临时文件中，该临时文件将与现有文件进行比较，以检查是否需要更新 (这避免了仅仅为了更新线参考或 POT-Creation-Date 字段而更改 POT)。

gettextize($$)
    此函数从两个目录 (一个原始目录和一个翻译目录) 生成一个翻译后的消息目录。这个过程在 po4a(7) 这一章节 Gettextization: how does it work? 中描述。

filter($)
    此函数用于从现有目录中提取目录。只有在给定文件中有引用的条目才会放入结果目录中。

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

    我有时喜欢 Perl ;)

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

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

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

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

    wrap
        指示我们是否可以认为字符串中的空格不重要的布尔值。如果是，则该函数在查找翻译之前对字符串进行规范化，并对结果进行封装。

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

stats_get()
    返回自上次调用 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";

stats_clear()
    清除有关 gettext 命中的统计信息。

用于构建消息目录的函数

push(%)
    在当前目录的末尾推送新条目。参数应形成哈希表。有效密钥为：

    msgid
        原始语言的字符串。

    msgstr
        翻译。

    reference
        指示找到此字符串的地点。示例：file.c:46(意思是在第 46 行的 'file.c' 中)。它可以是空格分隔列表，以防发生多次。

    comment
        此处手动添加的评论（由翻译人员）。此处的格式是免费的。

    automatic
        由字符串提取程序自动添加的注释。有关详细信息，请参阅 --add-comments 程序的 xgettext 选项。

    flags
        此条目的所有已定义标志的以空格分隔的列表。

        有效标志为： 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 文档。

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

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

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

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

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

        此信息不会写入 PO 文件。

其他功能

count_entries()
    返回目录中的条目数 (不带标题)。

count_entries_doc()
    返回文档中的条目数。如果一个字符串在文档中出现多次，则会对其进行多次计数。

equals_msgid(po)
    返回 ($uptodate, $diagnostic)，其中 $uptodate 指示当前 po 文件的所有 msgid 是否也出现在作为参数传递的参数中(所有其他字段在文件比较中被忽略)。非正式地，如果$uptodate 返回 false，那么在通过 po4a-updatepo 时 po 文件将被更改。

    如果 $uptodate 为 false，则 $diagnostic 包含对原因的诊断。

msgid($)
    返回给定数字的 msgid。

msgid_doc($)
    返回文档中具有给定位置的 msgid。

get_charset()
    返回 PO 标头中指定的字符集。如果没有设置，则返回 "UTF-8"。

set_charset($)
    这会将 PO 标头的字符集设置为其第一个参数中指定的值。如果您从不调用此函数(并且没有读取具有指定字符集的文件)，则默认值为 "UTF-8"。这个值不会改变这个模块的行为，它只是用来填充头中的字段，并在 get_charset() 中返回它。

作者
 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)