
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 名稱

po4a - 翻譯文件和其他資料的框架

=head1 簡介

po4a(PO For Anything) 使用經典的 gettext 工具簡化了文件翻譯的維護。po4a 的主要特徵是它將內容翻譯與文件結構分離。

本文件是對 po4a 專案的介紹，重點關注考慮是否使用此工具的潛在使用者，以及想要了解事物為什麼是這樣的好奇使用者。

=head1 為什麼是 po4a？

自由軟體的理念是讓技術真正為每個人所用。但許可並不是唯一的考慮因素：未翻譯的自由軟體對非英語國家的人來說毫無用處。因此，要讓每個人都可以使用軟體，我們還有一些工作要做。

大多數專案都很好地理解了這種情況，現在每個人都相信有必要翻譯所有的東西。然而，實際的翻譯代表了許多個人的巨大努力，他們因小小的技術困難而步履蹣跚。

值得慶幸的是，使用 gettext 工具套件實際上可以很好地翻譯開放原始碼軟體。這些工具用於從程式中提取要翻譯的字串，並以標準化格式(稱為 PO 檔案或翻譯目錄)顯示要翻譯的字串。一個完整的工具生態系統已經出現，可以幫助翻譯人員實際翻譯這些 PO 檔案。然後，gettext 在執行時使用結果向終端使用者顯示翻譯後的訊息。

然而，關於檔案，情況仍然有些令人失望。起初，翻譯文件似乎比翻譯程式更容易，因為您似乎只需複製文件原始檔並開始翻譯內容。然而，當原始文件被修改時，跟蹤修改很快就變成了翻譯人員的噩夢。如果手動完成，此任務會令人不快且容易出錯。

過時的翻譯往往比根本沒有翻譯更糟糕。終端使用者可能會被描述程式舊行為的文件所欺騙。此外，他們不能直接與維護人員互動，因為他們不會說英語。此外，維護員無法修復該問題，因為他們並不瞭解文件翻譯所用的每種語言。這些困難通常是由糟糕的工具造成的，可能會削弱志願翻譯人員的積極性，進一步加劇問題。

B<po4a 專案的目標是簡化文件翻譯人員的工作>。具體地說，它使文件翻譯 I<Maintenance> 變得可維護。

我們的想法是重用 gettext 方法並使其適用於該領域。與 gettext 一樣，文字從其原始位置提取，並作為 PO 翻譯目錄呈現給翻譯人員。翻譯人員可以利用經典的 gettext 工具來監控要進行的工作，並以團隊形式進行協作和組織。然後，po4a 將翻譯直接注入到文件結構中，以生成翻譯後的原始檔，可以像處理和分發英語檔案一樣處理和分發這些原始檔。任何未翻譯的段落都將以英語保留在生成的文件中，從而確保終端使用者在文檔中永遠不會看到過時的翻譯。

這使翻譯維護的大部分繁瑣工作自動化。發現需要更新的段落變得非常容易，當元素重新排序而不需要進一步修改時，這個過程是完全自動的。還可以使用特定驗證來減少導致文件損壞的格式化錯誤的機會。

有關此方法的優點和缺點的更完整列表，另請參閱本文件下面的 B<FAQ>。

=head2 支援的格式

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

=over 

=item man (成熟解析器)

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

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

=item AsciiDoc (成熟的解析器)

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

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

=item pod (成熟的解析器)

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

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

=item sgml (成熟的解析器)

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

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

=item TeX / LaTeX (成熟的解析器)

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

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

=item text (成熟解析器)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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



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

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

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

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

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

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

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

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

=item 其他支援的格式

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

=item 不支援的格式

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

=back

=head1 使用 po4a

從歷史上看，po4a 是圍繞四個指令碼構建的，每個指令碼都完成特定的任務。L<po4a-gettexalize(1)> 幫助引導翻譯，並可選擇將現有翻譯專案轉換為 po4a。L<po4a-updatepo(1)> 將對原始文件的更改反映到相應的 po 檔案中。L<po4a-late(1)> 從原始檔案和相應的 PO 檔案構建翻譯後的原始檔。此外，L<po4a-Normalize(1)> 對於除錯 po4a 解析器非常有用，因為它從原始文件生成一個未翻譯的文件。它使發現解析過程引入的故障變得更容易。

Most projects only require the features of L<po4a-updatepo(1)> and L<po4a-translate(1)>, but these scripts proved to be cumbersome and error prone to use. If the documentation to translate is split over several source files, it is difficult to keep the PO files up to date and build the documentation files correctly. As an answer, a all-in-one tool was provided: L<po4a(1)>. This tool takes a configuration file describing the structure of the translation project: the location of the PO files, the list of files to translate, and the options to use, and it fully automates the process. When you invoke L<po4a(1)>, it both updates the PO files and regenerate the translation files that need to. If everything is already up to date, L<po4a(1)> does not change any file.

本節的其餘部分將概述如何使用 po4a 的指令碼介面。大多數使用者可能更喜歡使用 L<po4a(1)> 文件中描述的多合一工具。

=head2 Po4a 指令碼的概述圖

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

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

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

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

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

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

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

=head2 開始新的翻譯

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

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

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

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

=head2 將更改整合到原始文件

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

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

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

=head2 生成翻譯的文件

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

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

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

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

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

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

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

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

 PO4A-HEADER: mode=eof

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

=pod

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

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

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

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

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

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

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

您還可以將插入I<mode> 設定為值 C<before>，具有類似的語義：將 C<mode=before> 與 C<endboundary> 組合將把附錄正好放在匹配邊界 B<after>，即 C<position> 之前的最後一條潛在邊界線。將 C<mode=before> 與 C<beginboundary> 組合將把附錄放在匹配邊界 B<before>，也就是 C<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(檔案結尾)

=head3 關於附錄的提示和技巧

=over 

=item 

請記住，這些是 regexp(正則表示式)。例如，如果您希望匹配以行 C<.fi> 結尾的 nroff 部分的末尾，請不要將 C<.fi> 用作 B<endboundary>，因為它將與 C<the[fi]le> 匹配，這顯然不是您所期望的。在這種情況下，正確的 B<endboundary> 是：C<^\.fi$>。

=item 

空格在 C<position> 和邊界的內容中很重要。所以下面的兩行 B<are different>。只有在翻譯的文件中有足夠的尾隨空格時，才會找到第二個空格。

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

=item 

儘管該上下文搜尋可能被認為是對 B<translated> 文件的每一行進行粗略操作，但它實際上是對已翻譯文件的內部資料串進行操作。該內部資料串可以是跨越包含多行的段落的文字，或者可以是單獨的 XML 標籤。附錄的確切 I<insertion point> 必須在內部數據字串之前或之後，並且不能在內部資料字串內。

=item 

將 B<-vv> 引數傳遞給 po4a 以瞭解如何將附錄新增到翻譯中。當您的附錄不適用時，在除錯模式下執行 po4a 以檢視實際的內部資料字串也可能會有所幫助。

=back

=head3 附錄示例

=over 

=item 

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

  .SH "作者"

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

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

=item 

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

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

=item 

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

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

=back



=head3 更詳細的示例

原始檔案(POD 格式)：

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

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

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

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

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

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

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

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

=head1 它是如何工作的？

本章將向您簡要介紹 po4a 的內部結構，以便您可以更有信心地幫助我們維護和改進它。它還可能幫助您理解為什麼它沒有達到您的預期，以及如何解決您的問題。

Po4a 體系結構面向物件。L<Locale::Po4a::TransTractor(3pm)|TransTractor> 類是所有 po4a 解析器的共同祖先。這個奇怪的名稱來自一個事實，即它同時負責翻譯文件和提取字串。

更正式地說，它需要一個要翻譯的文件加上一個包含要用作輸入的翻譯的 PO 檔案，同時生成兩個單獨的輸出：另一個 PO 檔案(從輸入文件中提取可翻譯字串的結果)和一個翻譯文件(結構與輸入文件相同，但所有可翻譯字串都替換為輸入 PO 的內容)。以下是這一點的圖形表示：

   輸入文件 --\                             /---> 輸出文件
                     \      翻譯提取器::       /       (翻譯)
                      +-->--   解析()  --------+
                     /                           \
   輸入 PO --------/                             \---> 輸出PO
                                                         (提取)



這個小骨頭是所有 po4a 架構的核心。 如果省略輸入 PO 和輸出文件，則得到 B<po4a-gettextize>。 如果同時提供輸入而忽略輸出 PO，則得到 B<po4a-translate>。 B<po4a> 呼叫翻譯提取器兩次，並在這些翻譯提取器呼叫之間呼叫 B<msgmerge -U>，以提供一個配置檔案的一站式解決方案。 有關更多詳細資訊，請參見 L<Locale::Po4a::TransTractor(3pm)>。

=head1 使用 po4a 的開源專案

以下是在生產中使用 po4a 進行文件編制的專案的非常部分的列表。如果您想將您的項目新增到列表中，只需給我們傳送電子郵件(或合併請求)即可。

=over 

=item 

adduser (man): 使用者和組管理工具。

=item 

apt (man, docbook): Debian 包管理器。

=item 

aptitude (docbook, svg): Debian 基於終端的包管理器

=item 

L<F-Droid website|https://gitlab.com/fdroid/fdroid-website> (markdown): 適用於 Android 平臺的自由與開放原始碼軟體(FOSS)應用程式的可安裝目錄。

=item 

L<git|https://github.com/jnavila/git-manpages-l10n> (asciidoc): 用於跟蹤源代碼更改的分散式版本控制系統。

=item 

L<Linux manpages|https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (man)

該專案提供了將許多手冊頁翻譯成不同語言的基礎設施，可以整合到幾個主要的發行版中(Arch Linux、Debian 和衍生品、Fedora)。

=item 

L<Stellarium|https://github.com/Stellarium/stellarium> (HTML): 為您的計算機提供免費的開源天文館。po4a 用於翻譯天空文化描述。

=item 

其他要排序的專案：L<https://gitlab.com/fdroid/fdroid-website/> L<https://github.com/fsfe/reuse-docs/pull/61>

=back

=head1 常見問題解答

=head2 如何發音 po4a？

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

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

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

=over 

=item B<poxml>

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

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

=item B<po-debiandoc>

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

=item B<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.

=item B<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.

=back

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

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

=over 2

=item 

翻譯不會與原始版本一起儲存，這使得可以檢測翻譯是否過時。

=item 

翻譯被儲存在彼此獨立的檔案中，從而防止了不同語言的翻譯者在提交補丁時和檔案編碼級別上的相互干擾。

=item 

它在內部基於 B<gettext>（但是 B<po4a> 提供了一個非常簡單的介面，因此您無需了解內部使用它）。 這樣，我們不必重新實現，並且由於它們的廣泛使用，我們可以認為這些工具或多或少沒有錯誤。

=item 

終端使用者沒有任何變化(除了翻譯有望得到更好的維護)。 分發的結果文件檔案完全相同。

=item 

翻譯員不需要學習新的檔案語法，他們最喜歡的 PO 檔案編輯器(如 Emacs 的 PO 模式、Lokalize 或 GTranslator)就可以很好地工作。

=item 

gettext 提供了一種簡單的方法來獲取關於已經完成的工作、應該檢查和更新的工作以及仍要做的工作的統計資料。可以在這些地址找到一些示例：

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

=back

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

=over 2

=item 

附錄是…… 乍一看很奇怪。

=item 

您不能根據自己的喜好調整翻譯後的文字，比如在這裡拆分一個段落，在那裡加入另外兩個段落。但在某種意義上，如果原始版本有問題，無論如何都應該報告為 bug。

=item 

即使有一個簡單的介面，它仍然是一個人們必須學習的新工具。

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

=back

=head1 參見

=over 

=item 

您應該使用的多合一工具的文件：L<po4a(1)>。

=item 

單個 po4a 指令碼的文件： L<po4a-gettextize(1)>、L<po4a-updatepo(1)>、L<po4a-late(1)>、L<po4a-Normalize(1)>。

=item 

其他幫助指令碼：L<msgan typot(1)>、L<po4a-display-man(1)>、L<po4a-display-pod(1)>。

=item 

每種格式的解析器，特別是檢視每種格式接受的選項：L<Locale::Po4a::AsciiDoc(3pm)> L<Locale::Po4a::Dia(3pm)>, L<Locale::Po4a::Guide(3pm)>, L<Locale::Po4a::Ini(3pm)>, L<Locale::Po4a::KernelHelp(3pm)>, L<Locale::Po4a::Man(3pm)>, L<Locale::Po4a::RubyDoc(3pm)>, L<Locale::Po4a::Texinfo(3pm)>, L<Locale::Po4a::Text(3pm)>, L<Locale::Po4a::Xhtml(3pm)>, L<Locale::Po4a::Yaml(3pm)>, L<Locale::Po4a::BibTeX(3pm)>, L<Locale::Po4a::Docbook(3pm)>, L<Locale::Po4a::Halibut(3pm)>, L<Locale::Po4a::LaTeX(3pm)>, L<Locale::Po4a::Pod(3pm)>, L<Locale::Po4a::Sgml(3pm)>, L<Locale::Po4a::TeX(3pm)>, L<Locale::Po4a::Wml(3pm)>, L<Locale::Po4a::Xml(3pm)>.

=item 

核心基礎設施的實施：L<Locale::Po4a::TransTractor(3pm)> (particularly important to understand the code organization), L<Locale::Po4a::Chooser(3pm)>, L<Locale::Po4a::Po(3pm)>, L<Locale::Po4a::Common(3pm)>. 還請檢查原始碼樹中的 F<CONTRIBUTING.md> 檔案。

=back

=head1 作者

 Denis Barbier <barbier,linuxfr.org>
 Martin Quinson (mquinson#debian.org)

