概述圖¶

 主文件       ---+---->-------->---------+
  （文件編寫）    |                       |
                V  （po4a 執行）         >----+--> 翻譯
                |                       |     |
現有的 PO 檔案  -->--> 更新的 PO 檔案>    -+|
      ^                  |               |
      |                  V               |
      +----<------<------+               ^
          （人工翻譯過程）                  |
                                         |
附錄 -->--------------------------- ------+

主文件由文件作者編寫。任何更改都會由 po4a 自動反映在 PO 檔案中，然後由翻譯人員進行更新。對採購訂單檔案的所有更改（手動或透過 po4a）都會自動反映在翻譯的文檔中。您可以使用 makefile 中的 po4a updatepo(1) 和 po4a translate(1) 腳本模擬此行為，但這很快就會變得麻煩和重複（請參見 po4a(7)）。強烈建議在構建過程中使用 po4a程式。

選項修改 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 或更高版本，並在預設情況下啟用。

查詢 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