名称

       po4a-gettexalize-convert 将原始文件(及其翻译)转换为 PO 文件

简介

       po4a-gettextize -f fmt -m master.doc [-l XX.doc] -p XX.po

       (XX.po is the output, all others are inputs)

描述

       po4a (PO 代表任何东西)使用经典的 gettext 工具简化了文档翻译的维护。po4a 的主要特点是将内容
       的翻译与文档结构分离。请参阅 po4a(7) 页了解本项目的详细介绍。

       po4a-gettex 脚本负责将文档文件转换为 PO 文件。您只需要使用它来设置您的 po4a 翻译项目，之后
       就不需要了。

       如果从头开始，po4a-gettextize 从文档中提取可翻译字符串并编写 POT 文件。如果使用 -l 标志提
       供以前存在的翻译文件，po4a-gettextize 将尝试使用它所包含的 PO 文件中的翻译。此过程仍然繁琐
       和手动，如下面的"将手动翻译转换为 po4a"一节所述。

       如果主文档具有非 ASCII 字符，则新生成的 PO 文件将表示为 UTF-8。否则（如果主文档完全在
       ASCII 中），生成的 PO 将使用已翻译输入文档的编码，如果未提供翻译文档，则使用 UTF-8。

选项

       -f, --format
           要处理的文档的格式。使用 --help-format 帮助格式选项查看可用格式的列表。

       -m, --master
           包含要翻译的主文档的文件。如果要对多个文档进行文本化，可以多次使用此选项。

       -M, --master-charset
           包含要翻译的文档的文件的字符集。

       -l, --localized
           包含本地化（已翻译）文档的文件。如果提供了多个主文件，您可能希望多次使用此选项提供多个
           本地化文件。

       -L, --localized-charset
           包含本地化文档的文件的字符集。

       -p, --po
           消息目录应写入的文件。如果未给出，消息目录将写入标准输出。

       -o, --option
           要传递给格式插件的额外选项。有关有效选项及其含义的更多信息，请参阅每个插件的文档。例
           如，您可以将 '-o tablecells' 传递给 AsciiDoc 解析器，而文本解析器将接受 '-o
           tabs=split'。

       -h, --help
           显示简短的帮助消息。

       --help-format
           列出 po4a 理解的文档格式。

       -V, --version
           显示脚本的版本并退出。

       -v, --verbose
           增加程序的冗长程度。

       -d, --debug
           输出一些调试信息。

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

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

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

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

   将手动翻译转换为 po4a
       po4a-gettextize将尝试提取任何提供的翻译文件的内容，并将此内容用作生成 PO 文件中的
       msgstr。请注意，此过程非常脆弱：翻译文件的第 N 字符串应该是原始第 N 字符串的翻译。除非两个
       文件共享完全相同的结构，否则这自然不起作用。

       在内部，每个 po4a 解析器报告每个提取字符串的语法类型。这是在 gettexted 期间检测到非同步化
       的。 例如，如果文件具有以下结构，则翻译中的第 4 个字符串（类型为"章节"）不太可能是原始第 4
       个字符串（类型为"段落"）的翻译。更有可能是将新段落添加到原稿中，或者两个原始段落在翻译中合
       并在一起。

           Original         Translation

         chapter            chapter
           paragraph          paragraph
           paragraph          paragraph
           paragraph        chapter
         chapter              paragraph
           paragraph          paragraph

       po4a-gettextize详细诊断任何检测到的结构不同步。发生这种情况时，应手动编辑文件（这可能需要
       您具有目标语言的一些概念）。您必须在其中一个文档中添加假段落或删除某些内容（或两者）以修复
       所报告的差异，直到两个文档的结构完全匹配。下一节将介绍一些技巧。

       即使成功处理文档，未检测到的差异和静默错误仍然是可能的。这就是为什么 po4a -gettextize 自动
       关联的任何翻译被标记为<fuzzy>需要人工检查。必须检查每个检索到的 msgstr 实际上是关联的
       msgid 的转换，而不是之前或之后的字符串。

       如您了解，此处的关键是翻译的文档和原始文档中具有完全相同的结构。最好的方法就是对用于翻译的
       master.doc 的确切版本进行文本化，并且仅在 gettextd 成功后针对最新的主文件更新 PO 文件。

       如果您足够幸运，在文件结构中拥有完美的匹配，则构建正确的 PO 文件需要几秒钟。否则，你很快就
       会明白为什么这个过程有这样一个丑陋的名称:)但请记住，这个咕咕的工作是代价，以获得舒适
       的po4a之后。转换后，主文档和翻译之间的同步将始终完全自动。

       即使事情出错，文本化通常仍然比再次翻译所有内容更快。尽管许多文档的结构已不同步，但我能够在
       一天内对整个 Perl 文档的现有法语翻译进行文本化。这是超过两兆字节的原始文本（200 万个字
       符）：从头开始翻译需要几个月的工作。

   获取文本化过程的提示和技巧
       检测到非同步一点后，gettextization 将停止。从理论上讲，在文档中的后期，使用与 diff(1) 实用
       程序相同的算法，可以重新同步获取文本化。但是，手动干预仍是必需的，以手动匹配无法自动匹配的
       元素，这解释了为什么未实现自动重新同步（尚未实现？）。

       当这种情况发生时，整个游戏归结到这些该死的文件的结构再次通过手动编辑对
       齐。po4a-gettextize关于它发生时哪里出了问题相当冗长。它报告不匹配的字符串、它们在文本中的
       位置以及每个字符串的类型。此外，到目前为止生成的 PO 文件将转储为 gettextization.failed.po
       ，以便进一步检查。

       下面是一些其他技巧，以帮助您在这个乏味的过程：

       •   删除翻译的所有额外内容，例如为译员提供学分的部分。以后可以使用附录将它们重新添加到
           po4a 中（请参阅 po4a(7)）。

       •   如果需要编辑文件以对齐其结构，则应尽可能选择编辑翻译。实际上，如果对原始版本的更改过于
           具有侵入性，则新旧版本在 PO 更新期间将不匹配，并且相应的翻译无论如何都会转储。但是，如
           果需要，不要犹豫，也编辑原始文档：重要的是获得第一个 PO 文件开始。

       •   不要犹豫，杀死任何原始内容，将不存在在翻译版本。将 PO 文件与文档同步时，以后将自动重新
           引入此内容。

       •   你或许应该告诉原作者翻译中似乎合理的任何结构变化。原始文档中的问题应报告给作者。在翻译
           中修复它们只会为社区的一部分修复它们。此外，使用 po4a 时不可能;)

       •   有时，段落内容确实匹配，但不匹配其类型。修复它与格式相当相关。在 POD 和人中，它通常来
           自这样一个事实，即其中一个包含以空白开头的行，而另一个则不包含。 在这些格式中，此类段
           落不能换行，因此成为不同的类型。只需删除空间，您就没事了。它也可能在 XML 中的标记名称
           中出现拼写错误。

           同样，当分隔线包含某些空格时，或者当 =item 行和项内容之间没有空行时，两个段落可能会合
           并到 POD 中。

       •   有时，取消同步消息似乎很奇怪，因为翻译附加到错误的原始段落。这是流程早期未检测到问题的
           迹象。通过检查 gettextization.failed.po 来搜索实际的取消同步点，并修复问题的实际所在。

       •   在一些不幸的环境中，你会觉得 po4a 吃了文本的某些部分，无论是原文还是翻
           译。gettextization.failed.po 表示两个文件都匹配到段落 N。但是，如果尝试（不成功），原
           始文件中的 N+1 段落不会与翻译中的 N+1 段落匹配，而是与 N+2 段落匹配。就像在文档中看到
           的 N+1 段落在过程中从文件中消失一样。

           当同一段落在文档中重复时，就会发生这种不幸的情况。在这种情况下，在 PO 文件中不会创建任
           何新条目，而是向现有引用添加新引用。

           因此，当两个相似但不同的段落以完全相同的方式翻译时，将发生前一种情况。这显然将删除翻译
           的一段。要解决此问题，请稍微更改文档中的一个翻译就足够了。您还可以选择终止原始文档中的
           第二段。

           相反，如果在原始文档中出现两次的同一段落在两个位置没有以完全相同的方式翻译，您就会感觉
           到原始文档中的一段刚刚消失。只需将最佳翻译复制到翻译文档中的另一个翻译，即解决问题。

       •   最后一点，如果 PO 文件的第一次同步需要很长时间，不要太惊讶。这是因为由 gettextization
           生成的 PO 文件的 msgid 与从最近主文件生成的 POT 文件的任何元素不完全匹配。这强制使用昂
           贵的字符串接近算法搜索最近的一个。

           例如，Perl 文档的法语翻译（5.5 MB PO 文件）的第一个 po4a-updatepo 花了大约 48 小时（是
           的，两天），而后续的 po4a-updatepo 文件只需十几秒。

参见

       po4a(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7).

作者

        Denis Barbier <barbier@linuxfr.org>
        Nicolas Francois <nicolas.francois@centraliens.net>
        Martin Quinson (mquinson#debian.org)

版权和许可

       版权所有 2002-2020，SPI，Inc.

       此程序是自由软件；您可以根据 GPL 条款重新分发和/或修改它(请参阅复制文件)。