Scroll to navigation

LOCALE::PO4A::TEX.3PM(1) User Contributed Perl Documentation LOCALE::PO4A::TEX.3PM(1)

名称

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

描述

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

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

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

使用 PO4A::TEX 进行翻译

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

There are some options (described in the next section) that can customize this behavior. If this doesn't fit to your document format you're encouraged to write your own derivative module from this, to describe your format's details. See the section WRITING DERIVATE MODULES below, for the process description.

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

此模块接受的选项

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

激活此模块某些内部机制的调试。 使用源查看哪些部件可以调试。
不应重新封装的环境的逗号分隔列表。

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

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

不应由 \input 和 \include 包含的文件的冒号分隔列表。
包含 po4a 定义的文件的名称，如 INLINE CUSTOMIZATION 部分中定义。 如果无法将定义放在要翻译的文档中，可以使用此选项。
应逐字处理的环境的逗号分隔列表。

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

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

在线定制

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

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

您可以在 command1 之前加上

一个星号 (*)
po4a 将从段落中提取此命令 (如果它位于段落的开头或结尾)。然后，翻译者必须翻译标记为可翻译的参数。
一个加号 (+)
对于星号，如果它出现在块的末端，命令将被提取，但参数不会单独转换。翻译器将不得不翻译连接到其所有参数的命令。这保留了更多的上下文，并且对于参数中包含较小单词的命令非常有用，这些命令可以有多种含义(和翻译)。

注意：在这种情况下，您不必指定哪些参数是可翻译的，但 po4a 必须知道参数的类型和数量。

一个减号 (-)
在这种情况下，不会从任何块中提取命令。但是如果它单独出现在块上，那么只有标记为可翻译的参数才会显示给翻译器。这对于字体命令很有用。这些命令通常不应该与它们的段落分开(以保持上下文)，但是如果整个字符串都包含在这样的命令中，就没有理由用它们来烦扰翻译人员。

The parameters argument is a set of [] (to indicate an optional argument) or {} (to indicate a mandatory argument). You can place an underscore (_) between these brackets to indicate that the parameter must be translated. For example:
% po4a: command *chapter [_]{_}

This indicates that the chapter command has two parameters: an optional (short title) and a mandatory one, which must both be translated. If you want to specify that the href command has two mandatory parameters, that you don't want to translate the URL (first parameter), and that you don't want this command to be separated from its paragraph (which allow the translator to move the link in the sentence), you can use:
% po4a: command -href {}{_}

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

% po4a: environment env parameters
This defines the parameters accepted by the env environment and specifies the ones to be translated. This information is later used to check the number of arguments of the \begin command. The syntax of the parameters argument is the same as described for the others commands. The first parameter of the \begin command is the name of the environment. This parameter must not be specified in the list of parameters. Here are some examples:
% po4a: environment multicols {}
% po4a: environment equation

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

% po4a: separator env "regex"
指示应根据给定正则表达式拆分环境。

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

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

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

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

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

编写衍生模块

添加字符串作为要在下一个翻译元素周围添加的注释。 这对于 texinfo 模块非常有用，因为注释在 TeX 中自动处理。
封装在转换器的翻译上，带有前后处理过滤器。

段落注释作为此段落第一个翻译字符串的 PO 注释插入。

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

如果在 %translate_buffer_env 中为当前环境定义了函数，则此函数将用于转换缓冲区，而不是 translate_buffer()。

重载翻译器的 read()。
递归读取文件，追加 @exclude_include 数组中未列出的包含文件。包含的文件是使用 KpathSea 库中的 kpseWhich 命令进行搜索的。

除了文件包含部分，它是从翻译提取器的读取中剪切并粘贴的。

用于使用 po4a 指令解析文件的子例程 (新命令的定义)。
解析格式为 "% po4a: " 的定义行。

有关更多详细信息，请参阅 INLINE CUSTOMIZATION 部分。

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

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

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

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

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

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

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

generic_command uses the information specified by register_generic_command or by adding definition to the TeX file:
% po4a: command command1 parameters

generic_environment uses the information specified by register_generic_environment or by adding definition to the TeX file:
% 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>

翻译

taotieren <admin@taotieren.com>

版权和许可

版权所有 © 2004, 2005 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.

This program is free software; you may redistribute it and/or modify it under the terms of GPL v2.0 or later (see the COPYING file).

2025-09-14 perl v5.40.1