支援的格式

目前，該方法已成功應用於多種文字格式：

man (成熟解析器)

很好的老手冊頁的格式，被那麼多的程式使用。po4a 支援在這裡非常受歡迎，因為這種格式使用起來有些困難，對新手也不是很友好。

Locale::Po4a::Man(3pm) 模組還支援 BSD 手冊頁使用的 MDOC 格式(它們在 Linux 上也很常見)。

AsciiDoc (成熟的解析器)

此格式是一種輕量級標記格式，旨在簡化文件的創作。例如，它用於記錄 git 系統。這些手冊頁是使用 po4a 翻譯的。

有關詳細資訊，請參閱 Locale::Po4a::AsciiDoc。

pod (成熟的解析器)

這是 Perl 線上文件格式。除了大多數現有的 Perl 指令碼之外，還使用此格式記錄了語言和擴充套件本身。透過將文件和實際程式碼嵌入到同一檔案中，可以輕鬆地使文件接近實際程式碼。它使程式設計師的工作變得更容易，但不幸的是，在您使用 po4a 之前，翻譯員的工作並非如此。

有關詳細資訊，請參閱 Locale::Po4a::Pod。

sgml (成熟的解析器)

即使現在被 XML 取代，這種格式仍然用於超過幾個螢幕的文件。它甚至可以用來製作完整的書籍。更新這種長度的文件可能非常困難。當原始文字在更新後重新縮排時，diff 通常顯示無用。幸運的是，po4a 可以在該過程之後幫助您。

目前只支援 DebianDoc 和 DocBook DTD，但是新增對新 DTD 的支援非常簡單。透過在命令列上提供所需的資訊，甚至可以在未知的 SGML DTD 上使用 po4a，而無需更改代碼。有關詳細資訊，請參見 Locale::Po4a::Sgml(3pm)。

TeX / LaTeX (成熟的解析器)

LaTeX 格式是自由軟體世界和出版物中使用的主要文件格式。

使用 Python 文件、一本書和一些簡報測試了 Locale::Po4a::LaTeX(3pm) 模組。

text (成熟解析器)

文字格式是包括長文字塊的許多格式的基本格式，包括 Markdown、Forties、YAML Front Matter 部分、Debian/Changelog 和 Debian/Control。

這支援靜態站點生成器、自述檔案和其他文件系統中使用的通用格式。有關詳細資訊，請參閱 Locale::Po4a::Text(3pm) 。

xml 和 XHMTL (可能是成熟的解析器)

XML 格式是許多文件格式的基本格式。

目前，po4a 支援 DocBook DTD (有關詳細資訊，請參閱 Locale::Po4a::Docbook(3pm) )和 XHTML。

BibTex (可能是成熟的解析器)

BibTex 格式與 LaTeX 一起用於設定參考文獻列表 (目錄) 的格式。

有關詳細資訊，請參閱 Locale::Po4a::BibTex。

Docbook (可能是成熟的解析器)

一種基於 XML 的標記語言，它使用語義標記來描述文件。

有關更多詳細資訊，請參閱 Locale::Po4a:Docbook 。

Guide XML (可能是成熟的解析器)

一種 XML 文件格式。此模組專門用於幫助支援和維護 Gentoo Linux 文件的翻譯，至少到 2016 年 3 月 (基於 Wayback Machine)。Gentoo 後來轉移到了 DevBook XML 格式。

有關更多詳細資訊，請參閱 Locale::Po4a:Guide。

Wml (可能是成熟的解析器)

Web 標記語言，不要將 WML 與手機上使用的 WAP 東西混淆。該模組依賴於 Xhtml 模組，而 Xhtml 模組本身又依賴於 XML 模組。

有關更多詳細資訊，請參閱 Locale::Po4a::Wml。

Yaml (可能是成熟的解析器)

JSON 的嚴格超集。YAML 通常用作系統或配置專案。YAML 是紅帽的 Ansible 的核心。

有關更多詳細資訊，請參閱 Locale::Po4a::Yaml 。

RubyDoc (可能是成熟的解析器)

Ruby 文件 (RD) 格式，在 2002 年轉換為 RDoC 之前，最初是 Ruby 和 Ruby 專案的預設文件格式。儘管顯然日文版的 Ruby 參考手冊仍然使用 RD。

有關更多詳細資訊，請參閱 Locale::Po4a::RubyDoc。

Halibut (高度實驗性的解析器)

由 PuTTY 的開發者 Simon Tatham 開發的文件生產系統，其元素類似於 TeX、debiandoc-sgml、TeXinfo 和其他。

有關更多詳細資訊，請參見 Locale::Po4a:Halibut。

Ini (高度實驗性的解析器)

MS-DOS 普及的配置檔案格式。

有關更多詳細資訊，請參閱 Locale::Po4a::Ini 。

texinfo (高度實驗性的解析器)

所有 GNU 文件都是以這種格式編寫的(這甚至是成為正式 GNU 專案的要求之一)。po4a 中對 Locale::Po4a::Texinfo(3pm) 的支援還處於起步階段。請報告錯誤和功能請求。

其他支援的格式

Po4a 還可以處理一些比較罕見或專門的格式，比如 2.4+ Linux 核心 (Locale::Po4a::KernelHelp) 的編譯選項文件或 dia 工具 (Locale::Po4a:Dia)生成的圖表。新增新格式通常非常簡單，主要任務是為您的目標格式提供一個解析器。有關這方面的更多資訊，請參見 Locale::Po4a::TransTractor(3pm)。

不支援的格式

不幸的是，po4a 仍然缺乏對幾種文件格式的支援。它們中的許多在 po4a 中都很容易支持。這不僅包括用於文件的格式，例如軟體包描述 (deb 和 rpm)、軟體包安裝指令碼問題、軟體包更改日誌，以及遊戲場景或 wine 資原始檔等程式使用的所有專用檔案格式。

Po4a 指令碼的概述圖

下面的模式概述瞭如何使用每個 po4a 指令碼。這裡，master.doc 是要翻譯的文件的示例名稱；XX.doc 是以 XX 語言翻譯的相同文件，而 doc.XX.po 是該文件以 XX 語言翻譯的目錄。文件作者主要關注 master.doc (可以是手冊頁、XML 文件、asciidoc 檔案或類似檔案)；翻譯人員主要關注 PO 檔案，而終端使用者只能看到 XX.doc 檔案。

                                   master.doc
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{翻譯}    |         { 更新到 master.doc }             :
     :           |                     |                        :
   XX.doc        |                     V                        V
 (可選)      |                 master.doc ->-------->------>+
     :           |                   (新的)                      |
     V           V                     |                        |
  [po4a-gettextize]   doc.XX.po -->+   |                        |
          |            (舊的)       |   |                        |
          |              ^         V   V                        |
          |              |     [po4a-updatepo]                  |
          V              |           |                          V
   translation.pot       ^           V                          |
          |              |        doc.XX.po                     |
          |              |         (模糊)                      |
   { 翻譯 }       |           |                          |
          |              ^           V                          V
          |              |     {手動編輯}                 |
          |              |           |                          |
          V              |           V                          V
      doc.XX.po --->---->+<---<-- doc.XX.po    addendum     master.doc
      (初始)                 (最新)  (可選)   (最新)
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                           [po4a-translate]
                                                  |
                                                  V
                                                XX.doc
                                             (最新)

此模式很複雜，但實際上，一旦設定和配置了專案，就只使用正確的部分(涉及 po4a-updatepo(1) 和 po4a-late(1) )。

左側部分描述瞭如何使用 po4a-gettexalize(1) 將現有的翻譯專案轉換為 po4a 基礎設施。此指令碼獲取原始文件及其翻譯的副本，並嘗試構建相應的 PO 檔案。這種手動轉換相當麻煩(有關更多詳細資訊，請參閱 po4a-gettexalize(1) 文件)，但轉換現有翻譯只需要一次。如果您沒有任何要轉換的翻譯，您可以忘掉這一點，專注於模式的正確部分。

在右上角，描述了原始作者的操作，更新了文件。右中部分描述了 po4a-updatepo(1) 的自動操作。提取新資料，並將其與現有翻譯進行比較。先前的翻譯用於未更改的部分，而部分修改的部分使用“模糊”標記連線到先前的翻譯，指示翻譯必須更新。新的或大量修改的資料未翻譯。

然後，Manual editing 報告描述了翻譯人員的操作，他們修改 PO 檔案，為每個原始字串和段落提供翻譯。這可以使用特定的編輯器(如 GNOME Translation Editor、KDE's Lokalize 或 poedit )或使用線上本地化平臺(如 weblate 或 pootle)來完成。翻譯結果是一組 PO 檔案，每種語言一個。有關更多詳細資訊，請參閱 gettext 文件。

圖的下半部分顯示了 po4a-translate(1) 如何從翻譯人員更新的 master.doc 原始文件和 doc.XX.po 翻譯目錄建立翻譯的源文件。文件的結構被重用，而原始內容被其翻譯的對應內容替換。或者，可以使用附錄向翻譯中新增一些額外的文字。這通常用於將翻譯人員的姓名新增到最終文件中。詳情見下文。

如前所述，po4a(1) 程式結合了分離指令碼的效果，在一次呼叫中更新 PO 檔案和翻譯後的文件。基本邏輯保持不變。

開始新的翻譯

如果使用 po4a(1)，則沒有特定的步驟來開始轉換。您只需在配置檔案中列出語言，就會自動建立丟失的 PO 檔案。自然，翻譯人員必須為您的文件中使用的每個內容提供翻譯。po4a(1)還建立 POT 檔案，即 PO 模板檔案。潛在的翻譯人員可以透過重新命名此檔案並提供其語言的翻譯，將您的專案翻譯成一種新的語言。

如果您喜歡單獨使用各個指令碼，則應該使用 po4a-gettexalize(1) 建立 POT 檔案，如下所示。然後可以將該檔案複製到 XX.po 以啟動新的翻譯。

  $ po4a-gettextize --format <format> --master <master.doc> --po <translation.pot>

Master 文件用於輸入，而 POT 檔案是此過程的輸出。

將更改整合到原始文件

為此使用的指令碼是 po4a-updatepo(1) (有關詳細資訊，請參閱其文件)：

  $ po4a-updatepo --format <format> --master <new_master.doc> --po <old_doc.XX.po>

在輸入中使用 master 文件，同時更新 PO 檔案：它在輸入和輸出中都使用。

生成翻譯的文件

完成翻譯後，您希望獲得翻譯後的文件，並將其與原始文件一起分發給使用者。為此，請使用 po4a-late(1) 程式，如下所示：

  $ po4a-translate --format <format> --master <master.doc> --po <doc.XX.po> --localized <XX.doc>

Master 檔案和 PO 檔案都用於輸入，而本地化檔案是此過程的輸出。

使用附錄向翻譯新增額外文字

從長遠來看，在手動翻譯檔案時，向翻譯中新增新文字可能是唯一更容易的事情 :)。當您想要向翻譯後的文件新增額外的部分，而不是與原始文件中的任何內容相對應時，就會發生這種情況。典型的用例是給翻譯團隊加分，並指出如何報告特定於翻譯的問題。

對於 po4a，您必須指定 addendum 檔案，這些檔案在概念上可以被視為在處理後應用於本地化文件的補丁。每個附錄必須作為單獨的檔案提供，但其格式與經典補丁程式非常不同。第一行是 header，它定義了附錄的插入點(不幸的是，使用了隱晦的語法--見下文)，而檔案的其餘部分被逐字新增到確定的位置。

標題行必須以字串 PO4A-HEADER: 開頭，後跟分號分隔的 key=value 字段列表。

例如，下面的標題聲明瞭一個附錄，該附錄必須放在翻譯的最後。

 PO4A-HEADER: mode=eof

當您想要在文件中間新增額外內容時，事情會更加複雜。下面的標題聲明瞭一個附錄，翻譯時必須放在包含字串 "About this document" 的 XML 部分之後。

 PO4A-HEADER: position=關於本文件; mode=after; endboundary=</section>

實際上，當嘗試應用附錄時，po4a 會搜尋與 "position" 引數匹配的第一行(這可以是 regexp(正則表示式))。不要忘記，po4a 在這裡考慮 translated 文件。本文件是英文的，但如果您打算將附錄應用於文件的法語翻譯，則您的行可能應該如下所示。

 PO4A-HEADER: position=關於本文件; mode=after; endboundary=</section>

一旦在目標文件中找到 "position",po4a 就會搜尋 "position" 之後的下一行，它與所提供的 "endboundary" 匹配。附錄被新增到該行的右側 after (因為我們提供了 endboundary，即結束於當前部分的邊界)。

使用下面的 Header 可以獲得完全相同的效果，即等效：

 PO4A-HEADER: position=關於本文件; mode=after; beginboundary=<section>

在這裡，po4a 在翻譯中的匹配 "About this document" 的行之後搜尋與 "<section"> 匹配的第一行，並新增該行的附錄 before ，因為我們提供了 beginboundary，即 邊界標記下一節的開始。 因此，此標題行需要將附錄放在包含 "about this document" 的部分之後，並指示 po4a 該部分以包含 "<section"> 標記的行開頭。 這與前面的示例等效，因為您真正想要的是在"/section"> 之後或 "<section">之前新增此附錄。

您還可以將插入mode 設定為值 "before"，具有類似的語義：將 "mode=before" 與 "endboundary" 組合將把附錄正好放在匹配邊界 after，即 "position" 之前的最後一條潛在邊界線。將 "mode=before" 與 "beginboundary" 組合將把附錄放在匹配邊界 before，也就是 "position" 之前的最後一條潛在邊界線。

  模式  |   邊界種類   |  使用的邊界  |  與邊界比較的插入點
 ========|===============|========================|=========================================
 'before'(之前)| 'endboundary'(結束邊界) | last before 'position'(‘位置’之前的最後一個) | Right after the selected boundary(就在所選邊界之後)
 'before'(之前)|'beginboundary'(開始邊界)| last before 'position' (‘位置’之前的最後一個)| Right before the selected boundary(就在所選邊界之前)
 'after'(之後) | 'endboundary'(結束邊界) | first after 'position'(‘位置’之後的第一個) | Right after the selected boundary(就在所選邊界之後)
 'after'(之後) |'beginboundary'(開始邊界)| first after 'position'(‘位置’之後的第一個) | Right before the selected boundary(就在所選邊界之前)
 'eof'(EOF)   |   (none) (無)     |  n/a                   | End of file(檔案結尾)

關於附錄的提示和技巧

• 請記住，這些是 regexp(正則表示式)。例如，如果您希望匹配以行 ".fi" 結尾的 nroff 部分的末尾，請不要將 ".fi" 用作 endboundary，因為它將與 "the[fi]le" 匹配，這顯然不是您所期望的。在這種情況下，正確的 endboundary 是："^\.fi$"。
• 空格在 "position" 和邊界的內容中很重要。所以下面的兩行 are different。只有在翻譯的文件中有足夠的尾隨空格時，才會找到第二個空格。

   PO4A-HEADER: position=關於本文件; mode=after; beginboundary=<section>
   PO4A-HEADER: position=關於本文件; mode=after; beginboundary=<section>
      

• 儘管該上下文搜尋可能被認為是對 translated 文件的每一行進行粗略操作，但它實際上是對已翻譯文件的內部資料串進行操作。該內部資料串可以是跨越包含多行的段落的文字，或者可以是單獨的 XML 標籤。附錄的確切 insertion point 必須在內部數據字串之前或之後，並且不能在內部資料字串內。
• 將 -vv 引數傳遞給 po4a 以瞭解如何將附錄新增到翻譯中。當您的附錄不適用時，在除錯模式下執行 po4a 以檢視實際的內部資料字串也可能會有所幫助。

附錄示例

• 如果要在以下 nroff 部分之後新增內容：

    .SH "作者"
      

  您應該透過設定 mode=After 選擇兩步方法。然後，您應該使用 position 引數 regex 將搜尋範圍縮小到 Authors 之後的行。然後，您應該將下一節的開頭(即，^\.SH)與 BEGINBOLDER 引數 regex 相匹配。這就是說：

   PO4A-HEADER:mode=after;position=作者;beginboundary=\.SH
      

• 如果您想要在給定行之後新增某些內容(例如，在“版權所有 Big Dude”行之後)，請使用與此行匹配的 position，mode=After，並給出與任何行匹配的 beginboundary。

   PO4A-HEADER:mode=after;position=版權所有 Big Dude，2004 年;beginboundary=^
      

• 如果要在文件末尾新增某些內容，請在文件的任意行加上匹配的 position (但只有一行，如果不是唯一的，po4a 將不會繼續)。並給出一個不匹配的 endboundary 。這裡不要使用像 "EOF" 這樣的簡單字串，而要使用那些在文件中出現的機會較小的字串。

   PO4A-HEADER:mode=after;position=關於本文件;beginboundary=FakePo4aBoundary
      

更詳細的示例

原始檔案(POD 格式)：

 |=head1 名稱
 |
 |dummy - 一個虛擬程式
 |
 |=head1 作者
 |
 |我

然後，以下附錄將確保在檔案的末尾新增有關翻譯器的部分（簡體中文）（簡體中文， "翻譯" 表示 "TRANSLATOR"，"我" 表示 "me"）。

 |PO4A-HEADER:mode=after;position=作者;beginboundary=^=head
 |
 |=head1 翻譯
 |
 |我
 |

要將附錄放在作者之前，請使用以下標題：

 PO4A-HEADER:mode=after;position=名稱;beginboundary=^=head1

這之所以可行，是因為“name”部分(在漢語中翻譯為“名稱”)之後與 beginboundary 匹配的下一行 /^=head1/ 是宣告作者的那行。因此，附錄將放在兩個部分之間。請注意，如果稍後在名稱和作者部分之間新增另一個部分，po4a 將錯誤地將附錄放在新部分之前。

要避免出現這種情況，您可以使用 mode=BEFORE 來完成相同的操作：

 PO4A-HEADER:mode=before;position=^=head1 AUTEUR

如何發音 po4a？

我個人把它念成 pouah <https://en.wiktionary.org/wiki/pouah>，這是一個法語擬聲詞，我們用它來代替 yuck(雅克 ) :) 我可能有一種奇怪的幽默感 :)

其他使用 gettext 的文件翻譯工具又如何呢？

There are a few of them. Here is a possibly incomplete list, and more tools are coming at the horizon.

poxml

這是 KDE 人員開發的處理 DocBook XML 的工具。AFAIK，它是第一個提取字串以從文檔轉換為 PO 檔案，並在轉換後注入它們的程式。

它只能處理 XML，並且只能處理特定的 DTD。我對列表的處理很不滿意，列表以一個大的 msgid 結尾。當清單變得很大時，大塊就變得更難處理了。

po-debiandoc

這個由 Denis Barbier 完成的程式是 po4a SGML 模組的一種前身，它或多或少地棄用了它。顧名思義，它只處理 DebianDoc DTD，這或多或少是一個過時的 DTD。

xml2po.py

Used by the GIMP Documentation Team since 2004, works quite well even if, as the name suggests, only with XML files and needs specially configured makefiles.

Sphinx

The Sphinx Documentation Project also uses gettext extensively to manage its translations. Unfortunately, it works only for a few text formats, rest and markdown, although it is perhaps the only tool that does this managing the whole translation process.

與它們相比，po4a 的主要優勢是易於新增額外內容(這一點更糟糕)，以及實現獲取文字的能力。

基於gettext 的方法的優點的摘要

• 翻譯不會與原始版本一起儲存，這使得可以檢測翻譯是否過時。
• 翻譯被儲存在彼此獨立的檔案中，從而防止了不同語言的翻譯者在提交補丁時和檔案編碼級別上的相互干擾。
• 它在內部基於 gettext（但是 po4a 提供了一個非常簡單的介面，因此您無需了解內部使用它）。 這樣，我們不必重新實現，並且由於它們的廣泛使用，我們可以認為這些工具或多或少沒有錯誤。
• 終端使用者沒有任何變化(除了翻譯有望得到更好的維護)。 分發的結果文件檔案完全相同。
• 翻譯員不需要學習新的檔案語法，他們最喜歡的 PO 檔案編輯器(如 Emacs 的 PO 模式、Lokalize 或 GTranslator)就可以很好地工作。
• gettext 提供了一種簡單的方法來獲取關於已經完成的工作、應該檢查和更新的工作以及仍要做的工作的統計資料。可以在這些地址找到一些示例：

   - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
   - http://www.debian.org/intl/l10n/
      

但是，並非所有事物都是綠色的，而且這種方法還存在一些必須解決的缺點。

• 附錄是…… 乍一看很奇怪。
• 您不能根據自己的喜好調整翻譯後的文字，比如在這裡拆分一個段落，在那裡加入另外兩個段落。但在某種意義上，如果原始版本有問題，無論如何都應該報告為 bug。
• 即使有一個簡單的介面，它仍然是一個人們必須學習的新工具。

  我的夢想之一是以某種方式將 po4a 整合到 GTranslator 或 Lokalize 中。開啟文件文件時，會自動提取字串，並且可以將翻譯後的檔案 + po 檔案寫入磁碟。如果我們設法制作 MSWord(TM) 模組(或者至少是 RTF)，專業翻譯人員甚至可以使用它。