LOCALE::PO4A::MAN.3PM(1)

名稱
Locale::Po4a::Man - 將手動頁面從/轉換為 PO 檔案

描述
Po4a (PO For Anything) 專案的目標是在文件等不需要翻譯的領域使用 gettext 工具簡化翻譯(更有趣的是，簡化翻譯的維護)。

Locale::Po4a::Man 是一個模組，用於幫助將 nroff 格式(手冊頁的語言)的文件翻譯成其他 [人類] 語言。

使用 PO4A::MAN 進行翻譯
這個模組非常努力地讓翻譯員的工作變得更容易。因此，呈現給翻譯人員的文字不是手冊頁中的文字的逐字副本。實際上，nroff 格式的粗略部分是隱藏的，這樣翻譯人員就不會把它們搞砸了。

  文字換行
未縮排的段落會自動為翻譯器重新換行。這可能會在生成的輸出中導致一些細微的差異，因為 groff 使用的重新包裝規則不是很清楚。例如，有時保留括號後的兩個空格。

無論如何，不同之處只在於換行段落中額外空格的位置，我認為這是值得的。

  字型規格
第一個更改是關於字型更改規範。在 nroff 中，有幾種方法可以指定給定的單詞應該用小寫、粗體還是斜體書寫。在要翻譯的文字中，只有一種方法，借用 POD (Perl Online Documentation) 格式：

I<text> -- 斜體文字
    等效於 \fItext\fP 或 ".I text"

B<text> -- 粗體文字
    等效於 \fBtext\fP 或 ".B text"

R<text> -- 羅馬文字
    等效於 \fRtext\fP

CW<text> -- 等長寬度文字
    等效於 \f(CWtext\fP 或 ".CW text"

備註：並非所有 groff 裝置都提供 CW 面。不推薦使用。這是為了您的方便而提供的。

  字元自動音譯
Po4a 會自動音譯某些字元，以簡化翻譯或稽核翻譯。以下是音譯的列表：

連字元 手冊頁中的連字元 (-) 和減號 (\-) 在 PO 檔案中都音譯為簡單的破折號 (-)。然後，在將翻譯插入到輸出文件中時，所有破折號都音譯為 roff 減號 (\-)。

    翻譯人員可以在翻譯中使用 roff 字形 '\[hy]' 強制使用連字元。

不間斷空格
    翻譯人員可以在翻譯中使用不間斷空格。這些不間斷空格 (latin1 中的 0xA0)將音譯為 roff 不間斷空格('\ ')。

引用音譯
    `` 和 '' 分別音譯為 \*(lq 和 \*(rq.

    為了避免這些音譯，翻譯人員可以插入零寬度 roff 字元(即分別使用 '\&' 或 '\&')。

  在翻譯中放 '<' 和 '>'
由於這些字元用於分隔字型修改後的部分，因此您不能逐字使用它們。改為使用 E<lt> 和 E<gt> (與 POD 中相同)。

此模組接受的選項
以下是此模組的特定選項：

debug
    啟用此模組某些內部機制的除錯。 使用源檢視哪些部件可以除錯。

verbose
    增加詳細程度。

groff_code
    此選項控制模組在遇到.de、.ie 或 .if 節時的行為。它可以採用下列值：

    fail
        這是預設值。遇到 .de、.ie 或 .if 章節時，模組將失敗。

    verbatim
        指示必須按原樣將 .de、.ie 或 .if 節從原始文件複製到翻譯後的文件。

    translate
        指示將為翻譯建議 .de、.ie 或 .if 章節。僅當這些部分之一中包含可翻譯字串時，才應使用此選項。否則，應該首選 verbatim。

generated
    該選項指定檔案是生成的，並且 po4a 不應嘗試檢測手冊頁是否由另一種格式生成。要在生成的手冊頁上使用 po4a，此選項是必需的。請注意，轉換生成的頁面而不是源頁面通常更脆弱，因此不是一個好主意。

mdoc
    此選項僅對 mdoc 頁面有用。

    它透過告訴 po4a 不翻譯 'NAME' 部分來選擇更嚴格的 mdoc 格式支援。翻譯了 'NAME' 部分的 mdoc 頁面不會生成任何頁首或頁尾。

    According to the groff_mdoc page, the NAME, SYNOPSIS and DESCRIPTION sections are mandatory. There are no known issues with translated SYNOPSIS or DESCRIPTION section, but you can also specify these sections this way:
     -o mdoc=NAME,SYNOPSIS,DESCRIPTION

    This mdoc issue can also be solved with an addendum like this one:
     PO4A-HEADER:mode=before;position=^.Dd
     .TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"

The following options specify the behavior of a user-defined macro (with a .de request), or of a classical macro that is not supported by po4a. They take as argument a comma-separated list of macros. For example:

 -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX

注意：如果某個宏不受 po4a 支援，並且您認為它是標準的 roff 宏，那麼您應該將其提交給 po4a 開發團隊。

untranslated
    untranslated 指示不必翻譯此宏(在其引數處)。

noarg
    noarg 類似於 untransted，不同之處在於 po4a 將驗證沒有引數新增到此宏。

translate_joined
    translate_joined 指示 po4a 必須提議翻譯宏的引數。

translate_each
    對於 translate_each，除了每個引數將被單獨翻譯外，還將為翻譯建議引數。

no_wrap
    該選項將逗號分隔的對列表 begin:end 作為引數，其中 begin 和 end 是分隔不應該重新換行的節的開始和結束的命令。

    注意：不執行任何測試來確保 end 命令與其 begin 命令匹配；任何結束命令都會停止 no_wrap 模式。如果您有一個沒有 end (分別是 begin )的 begin (分別是 end)宏，則可以指定現有的 end (如 fi)或 begin (如 nf)作為對應宏。這些宏 (及其引數) 不會被翻譯。

inline
    此選項指定不得拆分當前段落的逗號分隔宏列表。然後，要轉換的字串將包含 foo <.bar baz qux> quux，其中 bar 是應該內聯的命令，baz qux 是其參數。

unknown_macros
    此選項指示找到未知宏時 po4a 的行為。預設情況下，po4a 失敗並顯示警告。它可以採用以下值： failed (預設值)、untranslated、noarg、translate_joined 或 translate_each (有關這些值的解釋，請參見上文)。

創作符合 PO4A::MAN 的手冊頁
這個模組仍然非常有限，而且將永遠如此，因為它不是一個真正的 nroff 直譯器。做一個真正的 nroff 直譯器是可能的，允許作者使用所有現有的宏，甚至在他們的頁面中定義新的宏，但我們不想這樣做。這太難了，我們認為沒有必要。我們確實認為，如果手冊頁的作者想要看到他們的作品被翻譯，他們可能必須適應，以減輕翻譯人員的工作。

因此，po4a 中實現的 man 解析器有一些我們不太願意糾正的已知限制，如果您希望看到翻譯人員處理您的文件，這些限制將構成您必須避免的一些陷阱。

  不要在 nroff 中程式設計
nroff 是一種完整的程式語言，具有宏定義、條件等功能。因為這個解析器不是一個功能齊全的 nroff 直譯器，所以它在使用這些工具的頁面上將失敗 (我框中大約有200個這樣的頁面)。

  使用普通宏集
仍然有一些宏不受 po4a::man 支援。這只是因為我找不到任何關於它們的文件。這是我的計算機上使用的不受支援的宏的列表。請注意，此列表並不詳盡，因為程式在第一個遇到的不受支援的宏上失敗。如果您有關於這些宏的任何資訊，我很樂意新增對它們的支援。由於這些宏，po4a::man 無法訪問我框中的大約 250 個頁面。

 ..               ."              .AT             .b              .bank
 .BE              ..br            .Bu             .BUGS           .BY
 .ce              .dbmmanage      .do                             .En
 .EP              .EX             .Fi             .hw             .i
 .Id              .l              .LO             .mf
 .N               .na             .NF             .nh             .nl
 .Nm              .ns             .NXR            .OPTIONS        .PB
 .pp              .PR             .PRE            .PU             .REq
 .RH              .rn             .S<             .sh             .SI
 .splitfont       .Sx             .T              .TF             .The
 .TT              .UC             .ul             .Vb             .zZ

  從 po4a 隱藏文字
有時，作者知道有些部分是不可翻譯的，不應該用 po4a 提取。例如，選項可能接受 other 引數，並且 other 也可能顯示為列表的最後一項。在第一種情況下，other 應該是不可翻譯的。在第二種情況下，應該翻譯 other。

在這種情況下，作者可以避免 po4a 提取一些字串，使用一些特殊的 groff 結構：

 .if !'po4a'hide' .B other

(這將需要 -o groff_code=verbatim 選項)

A new macro can also be defined to automate this:
 .de IR_untranslated
 . IR \\$@
 ..

 .IR_untranslated \-q ", " \-\-quiet

(這將需要選項 -o groff_code=verbatim 和 -o untranslated=IR_untranslated；使用此構造，不嚴格需要 .if !'po4a'hide' 條件，因為 po4a 不會解析宏定義的內部)

or using an alias:
 .als IR_untranslated IR

 .IR_untranslated \-q ", " \-\-quiet

這將需要 -o untranslated=als,IR_untranslated 選項。

  結論
總結這一節，請保持簡單，在編寫手冊頁時不要試圖變得聰明。很多事情在 nroff 中是可能的，並且不被這個解析器支援。例如，不要試圖擾亂 \c 來中斷文字處理(就像我框中的 40 頁一樣)。或者，確保將宏引數與宏本身放在同一行。我知道它在 nroff 中是有效的，但是會使解析器過於複雜而無法處理。

當然，另一種可能是使用另一種更便於翻譯的格式(比如使用 po4a::pod 的 POD，或者像 SGML 這樣的 XML 家族之一)，但是多虧了 po4a::man，它不再需要了。也就是說，如果您的文件的源格式是 POD 或 XML，那麼轉換源格式而不是這個生成的格式可能更聰明。在大多數情況下，po4a::man 將檢測生成的頁面併發出警告。它甚至會拒絕處理 POD 生成的頁面，因為這些頁面由 po4a::pod 完美地處理，而且它們的 nroff 對應項定義了許多我不想編寫支援的新宏。在我的機器上，4323 個頁面中的 1432 個是從 POD 生成的，將被 po4a::man 忽略。

在大多數情況下， po4a::man 會發現問題並拒絕處理頁面，發出一個適應的訊息。在一些罕見的情況下，程式將沒有警告完成，但輸出將是錯誤的。這種情況稱為 "bugs"；如果遇到這種情況，請務必報告此情況，並在可能時進行修復…

此模組的狀態
此模組可用於大多數現有手冊頁。

一些測試定期在 Linux 機器上執行：

•   三分之一的頁面被拒絕，因為它們是從 po4a 支援的另一種格式 (例如 POD 或 SGML) 生成的。

•   10% 的剩餘頁面因錯誤而被拒絕(例如，不支援 groff 宏)。

•   然後，只有不到 1% 的頁面被 po4a 靜默接受，但存在重大問題 (即丟失單詞或插入新詞)

•   處理其他頁面時通常沒有比間距差異或換行更重要的差異 (只有不到 10% 的已處理頁面出現字型問題)。

另請參見
Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)

作者
 Denis Barbier <barbier@linuxfr.org>
 Nicolas François <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)

版權和許可
版權所有 © 2002-2008 SPI, Inc.

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).