Provided by: po4a_0.67-2_all 
名稱
po4a - 一次性更新 PO 檔案和翻譯文件
簡介
po4a [options] config_file
描述
po4a (PO 代表任何東西)使用經典的 gettext 工具簡化了文件翻譯的維護。po4a 的主要特點是將內容
的翻譯與文件結構分離。請參閱 po4a(7) 頁瞭解本專案的詳細介紹。
當您第一次執行 po4a 程式時，只有一個配置檔案和要翻譯的文件（稱為主文件），它會生成一個 POT
檔案（也稱為翻譯模板），其中包含文件中的所有可翻譯字串，格式可以簡化翻譯器的工作。
這些 POT 檔案可以使用特定的編輯器（如 GNOME Translation editor、KDE 的 Lokalize 或
poedit）進行翻譯，也可以整合到線上本地化平臺（如 weblate 或 pootle）中。翻譯結果是一組 PO
檔案，每種語言一個。
當您使用主文件和 PO 檔案執行 po4a 程式時，它透過將內容的翻譯（在 PO 檔案中找到）注入到原始
主文件的結構中來生成翻譯後的文件。
如果主文件同時發生了變化，po4a 將相應地更新 PO 和 POT 檔案，以便翻譯人員能夠輕鬆地檢測到修
改並更新他們的工作。根據您的設定，po4a 將丟棄部分翻譯的文件，或者生成一個混合了英語（對於
新的或修改過的段落）和目標語言（對於翻譯已經在 PO 檔案中的段落）的文件。
預設情況下，翻譯後的文件在至少 80% 的內容被翻譯時生成（請參見下面的 --keep 選項）。在翻譯
不到 100% 時立即丟棄譯文可能會讓譯者感到沮喪，而顯示太不完整的“譯文”可能會讓終端使用者感到
不安。
概述圖
主文件 ---+---->-------->---------+
（文件編寫） | |
V （po4a 執行） >----+--> 翻譯
| | |
現有的 PO 檔案 -->--> 更新的 PO 檔案> -+|
^ | |
| V |
+----<------<------+ ^
（人工翻譯過程） |
|
附錄 -->--------------------------- ------+
主文件由文件作者編寫。任何更改都會由 po4a 自動反映在 PO 檔案中，然後由翻譯人員進行更新。對
採購訂單檔案的所有更改（手動或透過 po4a）都會自動反映在翻譯的文檔中。您可以使用 makefile
中的 po4a updatepo(1) 和 po4a translate(1) 腳本模擬此行為，但這很快就會變得麻煩和重複（請
參見 po4a(7)）。強烈建議在構建過程中使用 po4a程式。
選項
-k, --keep
保留(即寫入)結果檔案的轉換百分比的最小閾值(預設值：80)。即，預設情況下，檔案必須至少翻
譯 80% 才能寫入磁碟。
-h, --help
顯示簡短的幫助訊息。
-M, --master-charset
包含要翻譯的文件的檔案字符集。請注意，所有主文件必須使用相同的字符集。
-L, --localized-charset
包含本地化文件的檔案字符集。請注意，所有翻譯的文件將使用相同的字符集。
-A, --addendum-charset
附錄的字符集。請注意，所有附錄應使用相同的字符集。
-V, --version
顯示指令碼的版本並退出。
-v, --verbose
增加程式的冗長程度。
-q, --quiet
減少程式的冗長。
-d, --debug
輸出一些除錯資訊。
-o, --option
要傳遞給格式外掛的額外選項。有關有效選項及其含義的更多資訊，請參閱每個外掛的文件。例
如，您可以將 '-o tablecells' 傳遞給 AsciiDoc 解析器，而文字解析器將接受 '-o
tabs=split'。
-f, --force
始終生成 POT 和 PO 檔案，即使 po4a 認為沒有必要。
預設行為(未指定 --force 時)如下：
如果 POT 檔案已經存在，則如果主文件或配置檔案較新(除非提供了 --no-update)，則會重
新生成該檔案。POT 檔案也寫入臨時文件中，po4a 驗證是否確實需要更改。
此外，只有當翻譯的主文件、PO 檔案、其中一個附錄或配置檔案更新時，才會重新生成翻
譯。要避免嘗試重新生成未透過閾值測試的翻譯(請參見 --KEEP)，可以建立擴充套件名為
.po4a-stamp 的檔案(請參見 --STAMP)。
如果主文件包含檔案，則應使用 --force 標誌，因為不會考慮這些包含檔案的修改時間。
PO 檔案總是基於帶有 msgmerge-U 的 POT 重新生成。
--stamp
告訴 po4a 在由於未達到閾值而未生成翻譯時建立標記檔案。這些戳記檔案根據預期的翻譯文件命
名，副檔名為 .po4a stamp。
注意：這隻會啟用 .po4a stamp 檔案的建立。如果存在戳記檔案，則始終使用它們，並使用 --rm
translations 或在最終翻譯檔案時刪除它們。
--no-translations
不生成翻譯的文件，只更新 POT 和 PO 檔案。
--no-update
不要更改 POT 和 PO 檔案，只能更新翻譯。
--keep-translations
即使翻譯不符合 --keep 指定的閾值，也保留現有翻譯檔案。此選項不會建立內容很少的新翻譯檔
案，但會儲存由於主檔案更改而衰減的現有翻譯。
警告：此標誌以一種相當劇烈的方式更改 po4a 行為：在翻譯改進之前，您的翻譯檔案根本不會更
新。僅當您希望傳送過時的翻譯文件而不是隻傳送準確的未翻譯文件時，才使用此標誌。
--rm-translations
刪除翻譯的檔案（意味著 --no translations）。
--no-backups
此標誌自 0.41 起不起作用，可能會在以後的版本中刪除。
--rm-backups
此標誌自 0.41 起不起作用，可能會在以後的版本中刪除。
--translate-only translated-file
只翻譯指定的檔案。如果配置檔案包含大量檔案，則加快處理速度可能會很有用。請注意，此選項
不更新 PO 和 POT 檔案。此選項可以多次使用。
--variable var=value
定義將在 po4a 配置檔案中展開的變數。每次出現 $(var) 都將被 value 替換。此選項可以多次
使用。
--srcdir SRCDIR
為 po4a 配置檔案中指定的所有輸入文件設定基本目錄。
如果同時指定了 destdir 和 srcdir，則按順序在以下目錄中搜索輸入檔案：destdir、當前目錄
和 srcdir。如果指定，輸出檔案將寫入 destdir 或當前目錄。
--destdir DESTDIR
為 po4a 配置檔案中指定的所有輸出文件設定基本目錄（請參見上面的 --srcdir）。
選項修改 POT 頭
--porefs type
指定引用格式。引數 type 可以是以下值之一：never 不生成任何引用；file 只指定不帶行號的
檔案；counter 用遞增的計數器替換行號；full 包含完整引用（預設值：full）。
--wrap-po no|newlines|number (default: 76)
指定應如何封裝 po 檔案。這使我們可以選擇封裝良好但可能導致 git 衝突的檔案，或者更容易
自動處理但對人類來說更難讀取的檔案。
從歷史上看，gettext 套件已經重新格式化了第 77 列化妝品的 po 檔案。此選項指定 po4a 的行
為。如果設定為數值，po4a 將在內容中的此列和換行之後封裝 po 檔案。如果設定為
newlines，po4a 將只在內容中的新行之後拆分 msgid 和 msgstr。如果設置為 no，則 po4a 根本
不會封裝 po 檔案。引用註釋總是由我們在內部使用的 gettext 工具封裝。
請注意，此選項對 msgid 和 msgstr 的封裝方式（即，將換行符新增到這些字串的內容中）沒有
影響。
--master-language
包含要翻譯的文件的原始檔的語言。 請注意，所有主文件必須使用相同的語言。
--msgid-bugs-address email@address
設定 msgid 錯誤的報告地址。 預設情況下，建立的 POT 檔案沒有 Report-Msgid-Bugs-To 欄
位。
--copyright-holder string
在 POT 標頭中設定版權所有者。 預設值為“自由軟體基金會有限公司。”
--package-name string
設定 POT 標頭的程式包名稱。 預設值為“封裝”。
--package-version string
設定 POT 標頭的軟體包版本。 預設值為“版本”。
修改 PO 檔案的選項
--msgmerge-opt options
msgmerge(1) 的其他選項。
注意： $lang 將擴充套件為當前語言。
--no-previous
此選項從傳遞給 msgmerge 的選項中刪除 -previous。這是支援 0.16 之前的 gettext 版本所必
需的。
--previous
此選項 --previous 新增到傳遞給 msgmerge 的選項中。它需要 gettext 0.16 或更高版本，並在
預設情況下啟用。
配置檔案
po4a 需要一個配置檔案作為引數。此檔案必須包含以下元素：
• PO 檔案的路徑和專案中存在的語言列表;
• 可選地，一些全域性選項和所謂的配置別名，用作配置單個主檔案的模板;
• 要轉換的每個主檔案的列表以及特定引數。
所有行在方括號之間都包含一個命令，後跟其引數。註釋以字元 '#' 開頭，並一直執行到行的末
尾。您可以轉義行尾，將命令分散到幾行。
本頁提供了一些完整的示例，而其他示例可以在原始碼分發的 "t/cfg" 目錄中找到。
查詢 PO 和 POT 檔案
最簡單的解決方案是顯式指定 POT 和 PO 檔案的路徑，如下所示：
[po4a_paths] man/po/project.pot de:man/po/de.po fr:man/po/fr.po
首先指定 POT 檔案的路徑，然後指定德語和法語 PO 檔案的路徑。
可以按如下方式寫入相同的資訊，以降低複製/貼上錯誤的風險：
[po4a_langs] fr de
[po4a_paths] man/po/project.pot $lang:man/po/$lang.po
$lang 元件使用提供的語言列表自動展開，減少了新增新語言時出現複製/貼上錯誤的風險。
透過只提供包含翻譯專案的目錄的路徑，您可以進一步壓縮相同的資訊，如下所示。
[po_directory] man/po/
提供的目錄必須包含一組 PO 檔案，每個檔名為 XX.po，"XX" 為此檔案中使用的語言的 ISO
639-1。該目錄還必須包含單個 POT 檔案，副檔名為 ".pot"。在第一次執行時，該檔案可以是空
的，但必須存在(po4a 無法猜測要在副檔名之前使用的名稱)。
請注意，您只能在 "po_資料夾" 和 "po4a_路徑" 之間選擇一個。第一個 ("po_檔案夾") 更緊湊，進
一步降低了複製/貼上錯誤的風險，但強制您使用預期的專案結構和文件名。第二個 ("po4a_路徑") 更
明確，可能更具可讀性，建議您在使用 po4a 設定第一個專案時使用。
集中或拆分 PO 檔案？
預設情況下，po4a 為每種目標語言生成一個 PO 檔案，其中包含翻譯專案的全部內容。隨著專案的增
長，這些檔案的大小可能會出現問題。使用 weblate 時，可以為每個翻譯段（即 msgid）指定優先順
序，以便首先翻譯重要的部分。儘管如此，一些翻譯團隊還是喜歡將內容分成幾個檔案。
要在每個主檔案中有一個 PO 檔案，只需在 "[po4a_paths]" 行上的 PO 檔名中使用字串 $master，如
下所示。
[po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po
透過這一行，po4a 將為每個要翻譯的文件生成單獨的 POT 和 PO 檔案。例如，如果您有 3 個文件和
5 種語言，這將產生 3 個 POT 檔案和 15 個 PO 檔案。這些檔案按照 "po4a_paths" 模板上的指定命
名，並將 $master 替換為要翻譯的每個文件的基名。在名稱衝突的情況下，您可以使用 "pot=" 引數
指定要使用的 POT 檔案，如下所示。此功能還可用於將多個翻譯後的檔案組合到同一 POT 檔案中。
[po4a_langs] de fr ja
[po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
[type: xml] foo/gui.xml $lang:foo/gui.$lang.xml pot=foo-gui
[type: xml] bar/gui.xml $lang:bar/gui.$lang.xml pot=bar
[type: xml] bar/cli.xml $lang:bar/cli.$lang.xml pot=bar
在 split 模式下，po4a 在 PO 更新期間構建一個臨時概要，以便在所有 PO 檔案之間共享翻譯。如果
兩個 PO 檔案對同一字串有不同的翻譯，po4a 將此字串標記為 fuzzy，並將在包含此字串的所有 PO
檔案中提交兩個翻譯。當翻譯人員解除困惑時，翻譯將自動用於每個 PO 檔案中。
指定要翻譯的文件
您還必須列出應翻譯的文件。對於每個主檔案，必須指定要使用的格式解析器、要生成的轉換文件的位
置，以及一些可選的配置。下面是一個例子：
[type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
de:doc/de/mein_kram.sgml
[type: man] script fr:doc/fr/script.1 de:doc/de/script.1
[type: docbook] doc/script.xml fr:doc/fr/script.xml \
de:doc/de/script.xml
但同樣，這些複雜的行很難閱讀和修改，例如在新增新語言時。使用 $lang 模板重新組織內容要簡單
得多，如下所示：
[type: sgml] doc/my_stuff.sgml $lang:doc/$lang/my_stuff.sgml
[type: man] script.1 $lang:po/$lang/script.1
[type: docbook] doc/script.xml $lang:doc/$lang/script.xml
指定選項
有兩種型別的選項：po4a options 是 po4a 命令列選項的預設值，而 format options 用於更改格式
分析器的行為。作為 po4a options，您可以在配置檔案中指定 --keep 命令列引數的預設值是
50%，而不是 80%。Format options 記錄在每個解析模組的特定頁面上，例如
Locale::Po4a::Xml(3pm)。例如，您可以將 nostrip 傳遞給 XML 解析器，以不除去提取的字串周圍的
空格。
您可以為特定主檔案傳遞這些選項，甚至為該檔案的特定翻譯傳遞這些選項，使用 "opt:" 和
"opt_XX:" 作為 "XX" 語言。在下面的示例中， nostrip 選項被傳遞給 XML 解析器（對於所有語
言），而對於法語翻譯，閾值將降低到 0%（因此始終保持）。
[type:xml] toto.xml $lang:toto.$lang.xml opt:"-o nostrip" opt_fr:"--keep 0"
無論如何，這些配置塊必須位於行的末尾。必須先宣告檔案，然後才是附錄（如有）（見下文），然後
才是選項。配置塊的分組不是很重要，因為元素在內部連線為字元串。以下示例都是等效的：
[type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20" opt:"-o nostrip" opt_fr:"--keep 0"
[type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20 -o nostrip" opt_fr:"--keep 0"
[type:xml] toto.xml $lang:toto.$lang.xml opt:--keep opt:20 opt:-o opt:nostrip opt_fr:--keep opt_fr:0
請注意，生成 POT 檔案時不使用特定於語言的選項。例如，僅在構建法語翻譯時，不可能將 nostrip
傳遞給解析器，因為同一 POT 檔案用於更新每種語言。因此，唯一可以特定於語言的選項是生成翻譯
時使用的選項，如 "--keep" 選項。
配置別名
要將相同的選項傳遞給多個檔案，最好的方法是按如下所示定義類型別名。在下一個示例中，使用此
"test" 型別（即 "man" 型別的擴充套件）將 "--keep 0" 傳遞給每個意大利語翻譯。
[po4a_alias:test] man opt_it:"--keep 0"
[type: test] man/page.1 $lang:man/$lang/page.1
還可以對現有型別進行擴充套件，對別名使用相同的名稱，如下所示。這不是一個錯誤的遞歸定義。
[po4a_alias:man] man opt_it:"--keep 0"
[type: man] man/page.1 $lang:man/$lang/page.1
全域性預設選項
您還可以使用 "[options]" 行定義必須用於所有檔案的選項，無論其型別如何。
[options] --keep 20 --option nostrip
與命令列選項一樣，您可以縮寫配置檔案中傳遞的引數：
[options] -k 20 -o nostrip
選項優先權
每個源的選項都是串聯的，確保預設值可以很容易地被更具體的選項覆蓋。順序如下：
• "[options]" 行提供可由任何其他源重寫的預設值。
• 然後使用類型別名。特定於語言的設定將覆蓋適用於所有語言的設定。
• 特定於給定主檔案的設定將同時覆蓋預設設定和來自類型別名的設定。在這種情況下，特定於語言
的設定也會覆蓋全域性設定。
• 最後，po4a 命令列上提供的引數會覆蓋配置檔案中的任何設定。
示例
下面是一個示例，演示如何引用空格和引號：
[po_directory] man/po/
[options] --master-charset UTF-8
[po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\""
[type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
opt:"-k 75" opt_it:"-L UTF-8" opt_fr:--verbose
附錄：在譯文中增加額外內容
如果您想在翻譯中新增一個額外的部分，例如給翻譯人員加學分，那麼您需要在定義主檔案的行中定義
一個附錄。有關附錄檔案語法的更多詳細資訊，請參閱第 po4a(7) 頁。
[type: pod] script fr:doc/fr/script.1 \
add_fr:doc/l10n/script.fr.add
您還可以使用語言模板，如下所示：
[type: pod] script $lang:doc/$lang/script.1 \
add_$lang:doc/l10n/script.$lang.add
如果補遺不適用，翻譯將被丟棄。
附錄宣告的修飾符
在並非所有語言都提供附錄的情況下，或者當附錄列表從一種語言更改為另一種語言時，附錄修飾符可
以簡化配置檔案。修飾符是位於檔名之前的單個字元。
? 如果此檔案確實存在，請包括 appendment_path，否則不執行任何操作。
@ addendment_path 不是常規的附錄，而是一個逐行包含附錄列表的檔案。每個附錄前面都可以加上修
飾符。
! appendment_path 被丟棄，它不會被載入，也不會被任何進一步的附錄規範載入。
以下內容包括任何語言的附錄，但前提是該附錄存在。如果附錄不存在，則不會報告任何錯誤。
[type: pod] script $lang:doc/$lang/script.1 add_$lang:?doc/l10n/script.$lang.add
以下為每種語言的附錄清單：
[type: pod] script $lang:doc/$lang/script.1 add_$lang:@doc/l10n/script.$lang.add
過濾翻譯的字串
有時候，你想在翻譯過程中隱藏一些字串。為此，可以為主檔案指定一個 "pot_in" 引數，以指定在生
成 pot 檔案時要使用的檔名，而不是實際的主檔名。下面是一個例子：
[type:docbook] book.xml \
pot_in:book-filtered.xml \
$lang:book.$lang.xml
使用此設定，將從 book-filtered.xml （必須在呼叫 po4a 之前生成），而轉換後的檔案將從生成
book.xml 檔案. 因此，任何屬於F的字串 book.xml 檔案但不在 book-filtered.xml 不會包含在 PO
檔案中，從而阻止翻譯人員為其提供翻譯。因此，在生成翻譯的文件時，這些字串將保持不變。這自然
會降低翻譯的級別，因此您可能需要使用 "--keep" 選項來確保無論如何都會生成文件。
配置示例
待辦事項：這部分真的有用嗎？
假設您維護一個名為 foo 的程式，該程式有一個手冊頁 man/foo.1，該手冊頁自然只以英語維護。現
在，作為上游或下游維護者，您需要建立和維護轉換。首先，需要建立 POT 檔案，以便使用
po4a-gettextize(1) 傳送給轉換器。
因此，對於我們的情況，我們會將其稱為
cd man && po4a-gettextize -f man -m foo.1 -p foo.pot
然後，您可以將此檔案傳送到適當的語言列表，或在您的網站上的某個位置提供下載。
現在假設您在下一個版本釋出之前收到了三個翻譯：de.po（包括附錄 de.po)， sv.po 和 pt.po. 由
於您不想在新的翻譯到達時更改 Makefile，因此可以在 Makefile 中使用 po4a 和適當的配置檔
案。我們稱之為 po4a.cfg。在我們的示例中，如下所示：
[po_directory] man/po4a/po/
[type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \
add_$lang:?man/po4a/add_$lang/$lang.add opt:"-k 80"
在這個例子中，我們假設您生成的手冊頁（以及所有的 PO 和 addenda 檔案）應該儲存在當前目錄下
的 man/translated/$lang/（分別儲存在 man/po4a/PO/ 和 man/po4a/add\$lang/）中。在我們的示例
中，man/po4a/po/ 目錄將包括 de.po，de.po 和de.po，並且 man/po4a/add_de/ 目錄將包括 de.add.
注意修飾語 ? 的用法，因為只有德語翻譯(de.po)附有附錄。
要實際構建翻譯後的手冊頁，您需要(只需一次！)。在相應 Makefile 的 build 目標中新增以下行：
po4a po4a.cfg
設定好後，當新的翻譯版本到達時，您不需要建立 Makefile，也就是說，如果法國團隊向您傳送
fr.po 和 fr.add，那麼您只需將它們分別放在 man/po4a/po/ 和 man/po4a/add_fr/ 中，下一次構建
程式時，法語翻譯也會自動在 F 中構建。
請注意，您仍然需要一個合適的目標來安裝帶有英文的本地化手冊頁。
最後，如果您沒有將生成的檔案儲存到版本控制系統中， 您的 clean 目標中也需要一行：
-rm -rf man/translated
參見
po4a-gettextize(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7).
作者
Denis Barbier <barbier@linuxfr.org>
Nicolas Francois <nicolas.francois@centraliens.net>
Martin Quinson (mquinson#debian.org)
版權和許可
版權所有 2002-2020，SPI，Inc.
此程式是自由軟體；您可以根據 GPL 條款重新分發和/或修改它(請參閱複製檔案)。