PO4A

Section: Po4a 工具 (7)
Updated: 2024-01-29
Index Return to Main Contents
 

名稱

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

簡介

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

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

為什麼是 po4a?

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

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

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

Regarding documentation, however, the situation still somewhat disappointing. At first translating documentation may seem to be easier than translating a program as it would seem that you just have to copy the documentation source file and start translating the content. However, when the original documentation is modified, keeping track of the modifications quickly turns into a nightmare for the translators. If done manually, this task is unpleasant and error-prone.

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

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

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

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

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

支援的格式

目前,該方法已成功應用於多種文字格式:
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

The easiest way to use this tool in your project is to write a configuration file for the po4a program, and only interact with this program. Please refer to its documentation, in po4a(1). The rest of this section provides more details for the advanced users of po4a wanting to deepen their understanding.  

Detailed schema of the po4a workflow

Make sure to read po4a(1) before this overly detailed section to get a simplified overview of the po4a workflow. Come back here when you want to get the full scary picture, with almost all details.

In the following schema, master.doc is an example name for the documentation to be translated; XX.doc is the same document translated in the language XX while doc.XX.po is the translation catalog for that document in the XX language. Documentation authors will mostly be concerned with master.doc (which can be a manpage, an XML document, an AsciidDoc file, etc); the translators will be mostly concerned with the PO file, while the end users will only see the XX.doc file.

Transitions with square brackets such as "[po4a updates po]" represent the execution of a po4a tool while transitions with curly brackets such as "{ update of master.doc }" represent a manual modification of the project's files.

                                   master.doc
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{translation}    |         { update of master.doc }             :
     :           |                     |                        :
   XX.doc        |                     V                        V
 (optional)      |                 master.doc ->-------->------>+
     :           |                   (new)                      |
     V           V                     |                        |
  [po4a-gettextize]   doc.XX.po -->+   |                        |
          |            (old)       |   |                        |
          |              ^         V   V                        |
          |              |   [po4a updates po]                  |
          V              |           |                          V
   translation.pot       ^           V                          |
          |              |        doc.XX.po                     |
          |              |         (fuzzy)                      |
   { translation }       |           |                          |
          |              ^           V                          V
          |              |     {manual editing}                 |
          |              |           |                          |
          V              |           V                          V
      doc.XX.po --->---->+<---<-- doc.XX.po    addendum     master.doc
      (initial)                 (up-to-date)  (optional)   (up-to-date)
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                     [po4a updates translations]
                                                  |
                                                  V
                                                XX.doc
                                             (up-to-date)

Again, this schema is overly complicated. Check on po4a(1) for a simplified overview.

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

On the top right part, the action of the original author is depicted, updating the documentation. The middle right part depicts the automatic updates of translation files: the new material is extracted and compared against the exiting translation. The previous translation is used for the parts that didn't change, while partially modified parts are connected to the previous translation with a ``fuzzy'' marker indicating that the translation must be updated. New or heavily modified material is left untranslated.

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

The bottom part of the figure shows how po4a creates a translated source document from the master.doc original document and the doc.XX.po translation catalog that was updated by the translators. The structure of the document is reused, while the original content is replaced by its translated counterpart. Optionally, an addendum can be used to add some extra text to the translation. This is often used to add the name of the translator to the final document. See below for details.

Upon invocation, po4a updates both the translation files and the translated documentation files automatically.  

Starting a new translation project

If you start from scratch, you just have to write a configuration file for po4a, and you are set. The relevant templates are created for the missing files, allowing your contributors to translate your project to their language. Please refer to po4a(1) for a quick start tutorial and for all details.

If you have an existing translation, i.e. a documentation file that was translated manually, you can integrate its content in your po4a workflow using po4a-gettextize. This task is a bit cumbersome (as described in the tool's manpage), but once your project is converted to po4a workflow, everything will be updated automatically.  

Updating the translations and documents

Once setup, invoking po4a is enough to update both the translation PO files and translated documents. You may pass the "--no-translations" to po4a to not update the translations (thus only updating the PO files) or "--no-update" to not update the PO files (thus only updating the translations). This roughly corresponds to the individual po4a-updatepo and po4a-translate scripts which are now deprecated (see ``Why are the individual scripts deprecated'' in the FAQ below).  

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

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

對於 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>

Here, po4a searches for the first line matching "<section"> after the line matching "About this document" in the translation, and add the addendum before that line since we provided a beginboundary, i.e. a boundary marking the beginning of the next section. So this header line requires placing the addendum after the section containing "About this document", and instruct po4a that a section starts with a line containing the "<section"> tag. This is equivalent to the previous example because what you really want is to add this addendum either after "/section"> or before "<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 "作者"

You should select a two-step approach by setting mode=after. Then you should narrow down search to the line after AUTHORS with the position argument regex. Then, you should match the beginning of the next section (i.e., ^\.SH) with the beginboundary argument regex. That is to say:

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

如果您想要在給定行之後新增某些內容(例如,在“版權所有 Big Dude”行之後),請使用與此行匹配的 positionmode=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

 

它是如何工作的?

This chapter gives you a brief overview of the po4a internals, so that you may feel more confident to help us to maintain and to improve it. It may also help you to understand why it does not do what you expected, and how to solve your problems.  

TransTractors and project architecture

At the core of the po4a project, the Locale::Po4a::TransTractor(3pm) class is the common ancestor to all po4a parsers. This strange name comes from the fact that it is at the same time in charge of translating document and extracting strings.

More formally, it takes a document to translate plus a PO file containing the translations to use as input while producing two separate outputs: Another PO file (resulting of the extraction of translatable strings from the input document), and a translated document (with the same structure as the input one, but with all translatable strings replaced with content of the input PO). Here is a graphical representation of this:

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

This little bone is the core of all the po4a architecture. If you provide both input and disregard the output PO, you get po4a-translate. If you disregard the output document instead, you get po4a-updatepo. The po4a uses a first TransTractor to get an up-to-date output POT file (disregarding the output documents), calls msgmerge -U to update the translation PO files on disk, and builds a second TransTractor with these updated PO files to update the output documents. In short, po4a provides one-stop solution to update what needs to be, using a single configuration file.

po4a-gettextize also uses two TransTractors, but another way: It builds one TransTractor per language, and then build a new PO file using the msgids of the original document as msgids, and the msgids of the translated document as msgstrs. Much care is needed to ensure that the strings matched this way actually match, as described in po4a-gettextize(1).  

Format-specific parsers

All po4a format parsers are implemented on top of the TransTractor. Some of them are very simple, such as the Text, Markdown and AsciiDoc ones. They load the lines one by one using "TransTractor::shiftline()", accumulate the paragraphs' content or whatever. Once a string is completely parsed, the parser uses "TransTractor::translate()" to (1) add this string to the output PO file and (2) get the translation from the input PO file. The parser then pushes the result to the output file using "TransTractor::pushline()".

Some other parsers are more complex because they rely on an external parser to analyze the input document. The Xml, HTML, SGML and Pod parsers are built on top of SAX parsers. They declare callbacks to events such as ``I found a new title which content is the following'' to update the output document and output POT files according to the input content using "TransTractor::translate()" and "TransTractor::pushline()". The Yaml parser is similar but different: it serializes a data structure produced by the YAML::Tiny parser. This is why the Yaml module of po4a fails to declare the reference lines: the location of each string in the input file is not kept by the parser, so we can only provide ``$filename:1'' as a string location. The SAX-oriented parsers use globals and other tricks to save the file name and line numbers of references.

One specific issues arises from file encodings and BOM markers. Simple parsers can forget about this issue, that is handled by "TransTractor::read()" (used internally to get the lines of an input document), but the modules relying on an external parser must ensure that all files are read with an appropriate PerlIO decoding layer. The easiest is to open the file yourself, and provide an filehandle or directly the full string to your external parser. Check on "Pod::read()" and "Pod::parse()" for an example. The content read by the TransTractor is ignored, but a fresh filehandle is passed to the external parser. The important part is the "<:encoding($charset)" mode that is passed to the open() perl function.  

Po objects

The Locale::Po4a::Po(3pm) class is in charge of loading and using PO and POT files. Basically, you can read a file, add entries, get translations with the gettext() method, write the PO into a file. More advanced features such as merging a PO file against a POT file or validating a file are delegated to msgmerge and msgfmt respectively.  

Contributing to po4a

Even if you have never contributed to any Open Source project in the past, you are welcome: we are willing to help and mentor you here. po4a is best maintained by its users nowadays. As we lack manpower, we try to make the project welcoming by improving the doc and the automatic tests to make you confident in contributing to the project. Please refer to the CONTRIBUTING.md file for more details.  

使用 po4a 的開源專案

以下是在生產中使用 po4a 進行文件編制的專案的非常部分的列表。如果您想將您的項目新增到列表中,只需給我們傳送電子郵件(或合併請求)即可。
adduser (man): 使用者和組管理工具。
apt (man, docbook): Debian 包管理器。
aptitude (docbook, svg): Debian 基於終端的包管理器
F-Droid website <https://gitlab.com/fdroid/fdroid-website> (markdown): installable catalog of FOSS (Free and Open Source Software) applications for the Android platform.
git <https://github.com/jnavila/git-manpages-l10n> (asciidoc): 用於跟蹤源代碼更改的分散式版本控制系統。
Linux manpages <https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (man)

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

Stellarium <https://github.com/Stellarium/stellarium> (HTML): 為您的計算機提供免費的開源天文館。po4a 用於翻譯天空文化描述。
Jamulus <https://jamulus.io/> (markdown, yaml, HTML): a FOSS application for online jamming in real time. The website documentation is maintained in multiple languages using po4a.
其他要排序的專案:<https://gitlab.com/fdroid/fdroid-website/> <https://github.com/fsfe/reuse-docs/pull/61>
 

常見問題解答

 

如何發音 po4a?

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

Why are the individual scripts deprecated?

Indeed, po4a-updatepo and po4a-translate are deprecated in flavor of po4a. The reason is that while po4a can be used as a drop-in replacement to these scripts, there is quite a lot of code duplication here. Individual scripts last around 150 lines of codes while the po4a program lasts 1200 lines, so they do a lot in addition of the common internals. The code duplication results in bugs occuring in both versions and needing two fixes. One example of such duplication are the bugs #1022216 in Debian and the issue #442 in GitHub that had the exact same fix, but one in po4a and the other po4a-updatepo.

In the long run, I would like to drop the individual scripts and only maintain one version of this code. The sure thing is that the individual scripts will not get improved anymore, so only po4a will get the new features. That being said, there is no deprecation urgency. I plan to keep the individual scripts as long as possible, and at least until 2030. If your project still use po4a-updatepo and po4a-translate in 2030, you may have a problem.

We may also remove the deprecation of these scripts at some point, if a refactoring reduces the code duplication to zero. If you have an idea (or better: a patch), your help is welcome.  

其他使用 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/

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

Addenda are somewhat strange at the first glance.
您不能根據自己的喜好調整翻譯後的文字,比如在這裡拆分一個段落,在那裡加入另外兩個段落。但在某種意義上,如果原始版本有問題,無論如何都應該報告為 bug。
即使有一個簡單的介面,它仍然是一個人們必須學習的新工具。

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

 

另請參見

您應該使用的多合一工具的文件:po4a(1)。
單個 po4a 指令碼的文件: po4a-gettextize(1)、po4a-updatepo(1)、po4a-late(1)、po4a-Normalize(1)。
其他幫助指令碼:msgan typot(1)、po4a-display-man(1)、po4a-display-pod(1)。
每種格式的解析器,特別是檢視每種格式接受的選項:Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm), Locale::Po4a::Guide(3pm), Locale::Po4a::Ini(3pm), Locale::Po4a::KernelHelp(3pm), Locale::Po4a::Man(3pm), Locale::Po4a::RubyDoc(3pm), Locale::Po4a::Texinfo(3pm), Locale::Po4a::Text(3pm), Locale::Po4a::Xhtml(3pm), Locale::Po4a::Yaml(3pm), Locale::Po4a::BibTeX(3pm), Locale::Po4a::Docbook(3pm), Locale::Po4a::Halibut(3pm), Locale::Po4a::LaTeX(3pm), Locale::Po4a::Pod(3pm), Locale::Po4a::Sgml(3pm), Locale::Po4a::TeX(3pm), Locale::Po4a::Wml(3pm), Locale::Po4a::Xml(3pm).
核心基礎設施的實施:Locale::Po4a::TransTractor(3pm) (particularly important to understand the code organization), Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). 還請檢查原始碼樹中的 CONTRIBUTING.md 檔案。
 

作者

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


 

Index

名稱
簡介
為什麼是 po4a?
支援的格式
使用 po4a
Detailed schema of the po4a workflow
Starting a new translation project
Updating the translations and documents
使用附錄向翻譯新增額外文字
它是如何工作的?
TransTractors and project architecture
Format-specific parsers
Po objects
Contributing to po4a
使用 po4a 的開源專案
常見問題解答
如何發音 po4a?
Why are the individual scripts deprecated?
其他使用 gettext 的文件翻譯工具又如何呢?
基於gettext 的方法的優點的摘要
另請參見
作者

This document was created by using the manual pages.
Time: 00:28:50 GMT, January 29, 2024