名称

Locale::Po4a::TeX - 将 TeX 文档和衍生品从/转换为 PO 文件

描述

Po4a (PO For Anything) 项目的目标是在文档等不需要翻译的领域使用 gettext 工具简化翻译(更有趣的是，简化翻译的维护)。

Locale::Po4a::TeX 是一个帮助将 TeX 文档翻译成其他 [人类] 语言的模块。它还可以用作构建基于 TeX 文档的模块的基础。

用户可能应该使用 LaTeX 模块，它继承自 TeX 模块并包含常见 LaTeX 命令的定义。

使用 PO4A::TEX 进行翻译

此模块可直接用于处理通用 TeX 文档。这将把您的文档拆分成更小的块 (段落、逐字块，甚至更小的块，如标题或索引)。

有一些选项(将在下一节中介绍)可以自定义此行为。如果这不适合您的文档格式，我们鼓励您编写自己的派生模块，以描述您的格式的详细信息。有关流程描述，请参阅下面的 WRITING DERIVATIVE MODULES 小节。

该模块还可以通过 TeX 文件中以 "% po4a:" 开头的行进行定制。此过程在 INLINE CUSTOMIZATION 一节中介绍。

此模块接受的选项

以下是此模块的特定选项：

debug

激活此模块某些内部机制的调试。使用源查看哪些部件可以调试。

no_wrap

不应重新封装的环境的逗号分隔列表。

请注意，逐字和 no_wrap 环境之间存在差异。在逐字逐句的块中没有命令和注释分析。

如果此环境尚未注册，则 po4a 将考虑此环境不会接受任何参数。

exclude_include

不应由 \input 和 \include 包含的文件的冒号分隔列表。

definitions

包含 po4a 定义的文件的名称，如 INLINE CUSTOMIZATION 部分中定义。如果无法将定义放在要翻译的文档中，可以使用此选项。

verbatim

应逐字处理的环境的逗号分隔列表。

如果此环境尚未注册，则 po4a 将考虑此环境不会接受任何参数。

使用这些选项可以替代已定义命令的默认行为。

在线定制

TeX 模块可以使用以 % po4a: 开头的行进行自定义。这些行被解释为解析器的命令。可以识别以下命令：

% po4a: command command1 alias command2: 指示 command1 命令的参数应作为 command2 命令的参数处理。
% po4a: command command1 parameters: 这详细描述了 command1 命令的参数。此信息将用于检查参数的数量及其类型。
您可以在 command1 之前加上

一个星号 (*): po4a 将从段落中提取此命令 (如果它位于段落的开头或结尾)。然后，翻译者必须翻译标记为可翻译的参数。
一个加号 (+): 对于星号，如果它出现在块的末端，命令将被提取，但参数不会单独转换。翻译器将不得不翻译连接到其所有参数的命令。这保留了更多的上下文，并且对于参数中包含较小单词的命令非常有用，这些命令可以有多种含义(和翻译)。
注意：在这种情况下，您不必指定哪些参数是可翻译的，但 po4a 必须知道参数的类型和数量。
一个减号 (-): 在这种情况下，不会从任何块中提取命令。但是如果它单独出现在块上，那么只有标记为可翻译的参数才会显示给翻译器。这对于字体命令很有用。这些命令通常不应该与它们的段落分开(以保持上下文)，但是如果整个字符串都包含在这样的命令中，就没有理由用它们来烦扰翻译人员。

参数是一组 [] (表示可选的。参数) 或 {} (指示强制参数)。您可以在这些方括号之间加一个下划线 (_) 来表示。必须翻译该参数。例如：
% po4a: command *chapter [_]{_}

这表明章节命令有两个参数：可选的。 (简称) 和强制性的，都必须翻译。如果要指定 href 命令有两个必需参数，您不想转换 URL (第一个参数)，并且您。我不希望此命令与其段落 (允许。翻译器移动句子中的链接)，您可以使用：
% po4a: command -href {}{_}

在这种情况下，仅当段落仅由此 href 命令组成时，才使用指示必须翻译哪些参数的信息。

% po4a: environment env parameters

这允许定义 env 环境接受的参数。此信息稍后将用于检查。 \begin 命令，并允许指定必须翻译哪一个。 Parameters 参数的语法与。其他命令。 \begin 命令的第一个参数是环境的名称。不能在参数列表中指定此参数。以下是。下面是一些示例：
% po4a: 环境多层 {}
% po4a: 环境方程

至于命令，i<env> 前面可以有一个加号 (+)，表示 \begin 命令必须使用其所有参数进行转换。

% po4a: separator env "regex"

指示应根据给定正则表达式拆分环境。

正则表达式由引号分隔。它不应该创建任何反向引用。如果需要组，应使用 (?:)。它可能还需要一些逃脱。

例如，LaTeX 模块使用 "(?:&|\\\\)" 正则表达式分别翻译表的每个单元格(行用 '\\' 分隔，单元格用 '&' 分隔)。

环境的概念扩展为 PO 文件中显示的类型。这可用于拆分 title 命令的第一个强制参数中的 "\\\\"。在本例中，环境是 title{#1}。

% po4a: verbatim environment env

指示 env 是一个逐字环境。在此环境中将忽略注释和命令。

如果此环境尚未注册，则 po4a 将考虑此环境不会接受任何参数。

编写衍生模块

pre_trans
post_trans
add_comment: 添加字符串作为要在下一个翻译元素周围添加的注释。这对于 texinfo 模块非常有用，因为注释在 TeX 中自动处理。
translate: 封装在转换器的翻译上，带有前后处理过滤器。
段落注释作为此段落第一个翻译字符串的 PO 注释插入。
get_leading_command($buffer): 此函数返回：

命令名称: 如果在给定缓冲区的开头未找到命令，则此字符串将为空。只考虑可以分隔的命令。%separated_command 散列包含这些命令的列表。
变种: 这表明是否使用了变量。例如，可以在 sections 命令的末尾添加星号(*)，以指定不应对其进行编号。在本例中，此字段将包含 "*"。如果没有变量，则该字段为空字符串。
元组数组（参数类型、参数）: 参数类型可以是 '{' (对于强制参数) 或 '[' (对于可选参数)。
剩余的缓冲区: 删除此前导命令及其参数后缓冲区的其余部分。如果未找到命令，则不会触及原始缓冲区，并在此字段中返回。

get_trailing_command($buffer): 与 get_leading_command 相同，但适用于缓冲区末尾的命令。
translate_buffer: 通过将前导命令和尾随命令(应该分别转换的命令)从缓冲区中分离出来，递归地转换缓冲区。
如果在 %translate_buffer_env 中为当前环境定义了函数，则此函数将用于转换缓冲区，而不是 translate_buffer()。
read: 重载翻译器的 read()。
read_file: 递归读取文件，追加 @exclude_include 数组中未列出的包含文件。包含的文件是使用 KpathSea 库中的 kpseWhich 命令进行搜索的。
除了文件包含部分，它是从翻译提取器的读取中剪切并粘贴的。
parse_definition_file: 用于使用 po4a 指令解析文件的子例程 (新命令的定义)。
parse_definition_line: 解析格式为 "% po4a: " 的定义行。
有关更多详细信息，请参阅 INLINE CUSTOMIZATION 部分。
is_closed
parse
docheader

用于编写派生解析器的内部函数

命令和环境函数接受以下参数(除了 $self 对象之外)：

命令名称
变种
(类型、参数)元组的数组
当前环境

前 3 个参数由 get_leading_command 或 get_trailing_command 提取。

命令和环境函数返回命令及其参数和新环境的转换。

当找到 \begin 命令时，将调用环境函数。它们由 \begin 命令及其参数调用。

TeX 模块只提出一个命令函数和一个环境函数：generic_command 和 generic_environment。

generic_command 使用由指定的信息。 register_generic_command 或通过将定义添加到 TeX 文件：
% po4a: command command1 parameters

generic_environment 使用 register_generic_environment 或通过向 TeX 文件添加定义：
% po4a: environment env parameters

这两个函数将仅转换指定为可翻译的参数(带 '_')。generic_environment 将把环境的名称附加到环境堆栈中，而 generic_command 将在命令的名称后面加上参数的标识符(如 {#7} 或 [#2])。

此模块的状态

此模块需要更多测试。

它在一本书上进行了测试，并使用 Python 文档进行了测试。

待办事项清单使用PO4A：：XML进行转换

自动检测新命令: Tex 模块可以解析 newcommand 参数，并尝试猜测参数的数量、它们的类型以及是否应该转换它们。
环境分隔符的翻译: 当 \item 用作环境分隔符时，item 参数附加到以下字符串。
应将某些命令添加到环境堆栈: These commands should be specified by couples. This can be used to specify commands beginning or ending a verbatim environment.
其它: 各种其他点在源代码中都标记为 TODO。

已知缺陷

源代码中的各个点都被标记为 FIXME。

参见

Locale::Po4a::LaTeX(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)

作者

 Nicolas François <nicolas.francois@centraliens.net>

版权和许可

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