名称

       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)