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 文件。這將把您的文件拆分成更小的塊 (段落、逐字塊,甚至更小的塊,如標題或索引)。
有一些選項(將在下一節中介紹)可以自定義此行為。如果這不適合您的文件格式,我們鼓勵您編寫自己的派生模組,以描述您的格式的詳細資訊。有關流程描述,請參閱下面的 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>
版權和許可
版權所有 © 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).
2024-06-26 | perl v5.38.2 |