Locale::Po4a::TeX

名稱

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。

 Nicolas François <[email protected]>

版權和許可

此程式是自由軟體；您可以根據 GPL 條款重新分發和/或修改它(請參閱複製檔案)。

2023-01-03

Po4a