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>

版權和許可

版權所有 © 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