Provided by: po4a_0.69-1_all 
名稱
Locale::Po4a::Xml - 將 XML 文件和衍生內容從/轉換為 PO 檔案
描述
Po4a (PO For Anything) 專案的目標是在文件等不需要翻譯的領域使用 gettext 工具簡化翻譯(更有
趣的是，簡化翻譯的維護)。
Locale::Po4a::Xml 是一個幫助將 XML 文件翻譯成其他 [人類] 語言的模組。它還可以用作為基於
XML 的文件構建模組的基礎。
使用 PO4A::XML 進行轉換
此模組可直接用於處理通用 XML 文件。這將提取所有標記的內容，而不提取屬性，因為它是大多數基
於 XML 的文件中的文字寫入位置。
有一些選項 (將在下一節中介紹) 可以自定義此行為。如果這不適合您的文件格式，則鼓勵您編寫由此
衍生的您自己的模組，以描述您的格式的詳細資訊。有關過程描述，請參閱下面的 WRITING DERIVATE
MODULES 小節。
此模組接受的選項
全域性除錯選項會導致此模組顯示排除的字串，以檢視它是否跳過了重要內容。
以下是此模組的特定選項：
nostrip
防止它剝離提取字串周圍的空格。
wrap
考慮到空格並不重要，規範化要翻譯的字串，並對翻譯後的文件進行換行。自定義標記選項可以覆
蓋此選項。請參閱下面的 translated 選項。
unwrap_attributes
預設情況下，屬性是換行的。此選項禁用換行。
caseinsensitive
它使標籤和屬性搜尋以不區分大小寫的方式工作。如果定義了它，它會將 <BooK>laNG 和
<BOOK>Lang 視為 <book>lang。
escapequotes
輸出字串中的轉義引號。例如，建立供 Android 構建工具使用的字串資源時是必需的。
另請參閱：https://developer.android.com/guide/topics/resources/string-resource.html
includeexternal
定義後，外部實體將包括在生成的 (翻譯的) 文件中，並用於提取字串。如果未定義，則必須將外
部實體單獨轉換為獨立文件。
ontagerror
此選項定義模組遇到無效 XML 語法 (結束標記與最後一個開始標記不匹配) 時的行為。它可以採
用以下值：
fail
這是預設值。模組將退出，並出現錯誤。
warn
該模組將繼續執行，併發出警告。
silent
模組將繼續，沒有任何警告。
使用此選項時要小心。通常建議修復輸入檔案。
tagsonly
注意：此選項已棄用。
僅提取 tags 選項中指定的標記。否則，它將提取除指定標記之外的所有標記。
doctype
嘗試與文件的 doctype 的第一行匹配的字串(如果已定義)。如果不是，則會出現一條警告，指示
該文件的型別可能不正確。
addlang
指示標記的路徑 (例如，<bbb><aaa>) 的字串，其中 lang="..." 需要增加屬性。語言將定義為
PO 檔案的基本名稱，不帶任何 .po 副檔名。
optionalclosingtag
指示關閉標記是否可選的布林值（如 HTML 中所示）。預設情況下，缺少的關閉標記會引發根據
ontagerror 處理的錯誤。
tags
注意：此選項已棄用。您應該改用 translated 和 untranslated 選項。
要翻譯或跳過的以空格分隔的標籤列表。預設情況下，將排除指定的標記，但如果使用
"tagsonly" 選項，則只包含指定的標記。標記的格式必須是 <aaa>，但是您可以加入一些
(<bbb><aaa>)，說明標記 <aaa> 的內容只有在轉換為 <bbb> 標記時才會被轉換。
您還可以透過在標籤層次結構前面放置一些字元來指定一些標籤選項。例如，您可以放入 'W' (換
行) 或 'W' (不換行) 來覆蓋全域性 wrap 選項指定的預設行為。
例如：W<chapter><title>
attributes
要轉換的標記屬性的空格分隔列表。您可以按名稱指定屬性 (例如，"lang")，但可以在其前面加
上標記層次結構，以指定此屬性僅在其位於指定的標記中時才會被轉換。例如：<bbb><aaa>lang
指定只有當 lang 屬性在 <aaa> 標記中，並且它在 <bbb> 標記中時，lang 屬性才會被轉換。
foldattributes
不要轉換行內標籤中的屬性。相反，將標記的所有屬性替換為 po4a-id=<id>。
當屬性不應該被翻譯時，這很有用，因為這簡化了翻譯人員的字串，並避免了打字錯誤。
customtag
不應視為標記的以空格分隔的標記列表。這些標記被視為內聯標記，不需要關閉。
break
空格分隔的應中斷序列的標記列表。預設情況下，所有標籤都會打破順序。
標記的形式必須為 <aaa>，但如果標記 (<aaa>) 僅在另一個標記 (<bbb>) 內時才應考慮，則可以
聯接一些 (<bbb><aaa>)。
請注意，標記只能在 break、inline 、placeholder 或 customtag 設定字串之一中列出。
inline
應視為內聯的以空格分隔的標記列表。預設情況下，所有標籤都會打破順序。
標記的形式必須為 <aaa>，但如果標記 (<aaa>) 僅在另一個標記 (<bbb>) 內時才應考慮，則可以
聯接一些 (<bbb><aaa>)。
placeholder
應視為佔位符的以空格分隔的標記列表。佔位符不會打亂順序，但會單獨轉換佔位符的內容。
佔位符在其塊中的位置將使用類似於以下內容的字串進行標記：
<placeholder type=\"footnote\" id=\"0\"/>
標記的形式必須為 <aaa>，但如果標記 (<aaa>) 僅在另一個標記 (<bbb>) 內時才應考慮，則可以
聯接一些 (<bbb><aaa>)。
break-pi
預設情況下，處理指令(即 "<? ... ?>" 標記)作為內聯標記處理。如果希望將 PI 作為中斷標記
處理，請透過此選項。請注意，解析器將未處理的 PHP 標記作為處理指令進行處理。
nodefault
預設情況下，模組不應嘗試在任何類別中設定的標記的空格分隔列表。
如果您的標記按此模組的子類具有其預設設定，但您想要設定替代設定，則需要將該標記作為
nodefault 設定字串的一部分列出。
cpp 支援 C 預處理器指令。設定此選項時，po4a 將把預處理器指令視為段落分隔符。如果必須對 XML
檔案進行預處理，這一點很重要，因為否則，如果 po4a 認為它屬於當前段落，則指令可能會插入
到行的中間，並且預處理器無法識別它們。注意：預處理器指令只能出現在標記之間 (它們不能換
開標記)。
translated
要翻譯的標記的空格分隔列表。
標記的形式必須為 <aaa>，但如果標記 (<aaa>) 僅在另一個標記 (<bbb>) 內時才應考慮，則可以
聯接一些 (<bbb><aaa>)。
您還可以透過在標籤層次結構前面放置一些字元來指定一些標籤選項。這將覆蓋全域性 wrap 和
defaulttranslateoption 選項指定的預設行為。
w 標籤應該被翻譯，內容可以重新封裝。
W 標籤應該被翻譯，內容不應該被重新包裝。
i 標籤應該內聯翻譯。
p 標記應轉換為佔位符。
在內部，XML 解析器只關心以下四個選項： w W i p。
* 根據 break 選項，將 Break 中列出的標記設定為 w 或 W 。
* inline 中列出的標記設定為 i。
* placeholder 中列出的標記設定為 p。
* untranslated 中列出的標記未設定任何這些選項。
您可以透過使用 --debug 選項呼叫 po4a 來驗證實際的內部引數行為。
例如：W<chapter><title>
請注意，標籤應列在 translated 或 untranslated 設定字串中。
untranslated
您不想翻譯的以空格分隔的標籤列表。
標記的形式必須為 <aaa>，但如果標記 (<aaa>) 僅在另一個標記 (<bbb>) 內時才應考慮，則可以
聯接一些 (<bbb><aaa>)。
請注意，未翻譯標記中的可翻譯行內標記將被視為可翻譯中斷標記，i 設定將被刪除，w 或 W 將
根據 wrap 選項進行設定。
defaulttranslateoption
不在任何已翻譯、未翻譯、分隔符、內聯或佔位符中的標籤的預設類別。
這是 translated 中定義的一組字母，此設定僅對可翻譯標記有效。
編寫衍生模組
定義要轉換的標籤和屬性
最簡單的定製是定義希望解析器轉換哪些標記和屬性。這應該在 initialize 函式中完成。首先，您應
該呼叫 main initialize 來獲取命令列選項，然後將您的自定義定義附加到選項雜湊中。如果您想從
命令列處理一些新選項，您應該在呼叫 main initialize 之前定義它們：
$self->{options}{'new_option'}='';
$self->SUPER::initialize(%options);
$self->{options}{'_default_translated'}.=' <p> <head><title>';
$self->{options}{'attributes'}.=' <p>lang id';
$self->{options}{'_default_inline'}.=' <br>';
$self->treat_options;
您應該在衍生模組中使用 _default_inline, _default_break, _default_placeholder,
_default_translated, _default_untranslated, 和 _default_attributes 選項。這允許使用者使用
命令列選項覆蓋模組中定義的預設行為。
使用命令列選項覆蓋預設行為
如果您不喜歡這個 xml 模組及其派生模組的預設行為，則可以提供命令列選項來更改它們的行為。
請參閱 Locale::Po4a::Docbook(3pm),
覆蓋 found_string 功能
另一個簡單的步驟是重寫函式 "found_string"，該函式接收從解析器中提取的字元串，以便轉換它
們。 您可以控制要翻譯的字串，並在轉換本身之前或之後執行轉換。
它接收提取的文字、關於它所在位置的引用以及包含額外資訊的雜湊，以控制要翻譯哪些字串、如何翻
譯它們以及生成註釋。
這些選項的內容取決於字串的型別 (在此雜湊的條目中指定)：
type="tag"
找到的字串是可翻譯標籤的內容。條目 "tag_options" 包含模組 "tags" 選項中標記層次結構前
面的選項字元。
type="attribute"
表示找到的字串是可翻譯屬性的值。條目 "attribute" 具有該屬性的名稱。
它必須返回將替換翻譯文件中原始文字的文字。下面是這個函式的一個基本示例：
sub found_string {
my ($self,$text,$ref,$options)=@_;
$text = $self->translate($text,$ref,"type ".$options->{'type'},
'wrap'=>$self->{options}{'wrap'});
return $text;
}
在新的 Dia 模組中還有另一個簡單的示例，它只過濾一些字串。
修改標記型別 (TODO)
這是一個更復雜的方法，但它支援(幾乎)完全自定義。它基於雜湊列表，每個雜湊定義一種標記型別的
行為。應該對列表進行排序，以便最通用的標記位於最具體的標記之後(首先按開始排序，然後按結束
鍵排序)。要定義標記型別，您必須使用以下鍵進行散列：
beginning
在 "<" 之後指定標記的開始。
end 在 ">" 之前指定標記的末尾。
breaking
它會顯示這是否是中斷標記類。非中斷(內聯)標籤是可以作為另一個標籤內容的一部分的標籤。它
可以採用值 false (0)、true (1) 或 undefined。如果未定義此標記，則必須定義 f_breaking
函式，該函式將說明該類的具體標記是否為中斷標記。
f_breaking
它是一個函式，它將判斷下一個標記是否是中斷標記。如果 breaking 選項不是，則應該定義它。
f_extract
如果您將此鍵未定義，泛型提取函式將必須提取標記本身。對於那些可以在它們中擁有其他標記或
特殊結構的標籤來說，它很有用，所以主解析器不會錯亂。此函式接收一個布林值，該布林值表示
如果標記應該從輸入流中刪除，或者不應該刪除。
f_translate
此函式接收標記 (get_string_until() 格式)，並將轉換後的標記 (轉換後的屬性或所有需要的轉
換) 作為單個字串返回。
用於編寫派生解析器的內部函式
使用標記
get_path()
此函式返回從文件根到當前標記的路徑，格式為 <html><body><p>.
可以作為引數傳遞額外的標記陣列（不帶括號）。 這些路徑元素將新增到當前路徑的末尾。
tag_type()
此函式返回 tag_types 列表中適合輸入流中下一個標記的索引，如果它位於輸入檔案的末尾，則
返回 -1。
這裡，標記的結構以 < 開頭，以 > 結尾，並且可以包含多行。
這適用於透過 "$self->shiftline()" 和 "$self->unshiftline($$)" 間接儲存輸入文件資料和引
用的陣列 "@{$self->{TT}{doc_in}}"。
extract_tag($$)
此函式返回輸入流的下一個標記，而不以陣列形式結束，以維護來自輸入檔案的引用。 它有兩個
引數：標記的型別（由 tag_type 返回）和布林，指示是否應該從輸入流中刪除標記型別。
這適用於透過 "$self->shiftline()" 和 "$self->unshiftline($$)" 間接儲存輸入文件資料和引
用的陣列 "@{$self->{TT}{doc_in}}"。
get_tag_name(@)
此函式以 extract_tag 返回的陣列形式返回作為引數傳遞的標記名。
breaking_tag()
此函式返回一個布林值，該布林值表示輸入流中的下一個標記是否為中斷標記（內聯標記）。 它
保持輸入流不變。
treat_tag()
此函式用於轉換輸入流中的下一個標記。使用每種標籤型別的自定義翻譯功能。
這適用於透過 "$self->shiftline()" 和 "$self->unshiftline($$)" 間接儲存輸入文件資料和引
用的陣列 "@{$self->{TT}{doc_in}}"。
tag_in_list($@)
此函式返回一個字串值，表示第一個引數 (標記層次結構) 是否與第二個引數 (標記列表或標記層
次結構) 中的任何標記匹配。如果不匹配，則返回 0。否則，它返回匹配標記的選項(標記前面的
字元)或 1 (如果該標記沒有選項)。
使用屬性
treat_attributes(@)
此函式處理標記屬性的轉換。它接收沒有開始/結束標記的標記，然後找到屬性，並翻譯可翻譯的
屬性(由模組選項 attributes 指定)。這將返回一個帶有翻譯後的標記的純字串。
使用已標記的內容
treat_content()
此函式從輸入流獲取文字，直到下一個換行標記(不是內聯)。使用每種標記型別的自定義翻譯功能
對其進行翻譯。
這適用於透過 "$self->shiftline()" 和 "$self->unshiftline($$)" 間接儲存輸入文件資料和引
用的陣列 "@{$self->{TT}{doc_in}}"。
使用模組選項
treat_options()
此函式使用模組的選項 (在命令列或 initialize 函式中指定) 填充包含標記、屬性和內聯資料的
內部結構。
從輸入文件獲取文字
get_string_until($%)
此函式返回一個數組，該陣列包含輸入文件中的行（和引用），直到它找到第一個參數。 第二個
引數是選項雜湊。值 0 表示已禁用（預設值）和啟用 1。
有效選項包括：
include
這使得返回的陣列包含搜尋的文字
remove
這將從輸入中刪除返回的流
unquoted
這樣可以確保搜尋的文字位於任何引號之外
regex
這表示第一個引數是正則表示式，而不是普通字串
skip_spaces(\@)
此函式接收對段落的引用作為引數(格式由 get_string_until 返回)，跳過其標題空格並將其作為
簡單字串返回。
join_lines(@)
此函式返回一個包含引數陣列中文字的簡單字串（丟棄引用）。
此模組的狀態
此模組可以翻譯標記和屬性。
待辦事項清單使用PO4A：：XML進行轉換
DOCTYPE (ENTITIES)
對實體轉換的支援最低。它們是作為整體翻譯的，不考慮標籤。不支援多行圖元，並且在轉換過程中始
終重包裹圖元。
修改繼承模組中的標記型別（在 tag_types 中移動 $self 結構？)
參見
Locale::Po4a::TransTractor(3pm), po4a(7)
作者
Jordi Vilalta <jvprat@gmail.com>
Nicolas François <nicolas.francois@centraliens.net>
版權和許可
版權所有 © 2004 Jordi Vilalta <jvprat@gmail.com>
版權所有 © 2008-2009 Nicolas François <nicolas.francois@centraliens.net>
此程式是自由軟體；您可以根據 GPL 條款重新分發和/或修改它(請參閱複製檔案)。