.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "PO4A 7" .TH PO4A 7 "2020-08-19" "Po4a Tools" "Po4a Tools" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" po4a \- framework to translate documentation and other materials .SH "Introduction" .IX Header "Introduction" po4a (\s-1PO\s0 for anything) eases the maintenance of documentation translation using the classical gettext tools. The main feature of po4a is that it decouples the translation of content from its document structure. .PP This document serves as an introduction to the po4a project with a focus on potential users considering whether to use this tool and on the curious wanting to understand why things are the way they are. .SH "Why po4a?" .IX Header "Why po4a?" The philosophy of Free Software is to make the technology truly available to everyone. But licensing is not the only consideration: untranslated free software is useless for non-English speakers. Therefore, we still have some work to do to make software available to everybody. .PP This situation is well understood by most projects and everybody is now convinced of the necessity to translate everything. Yet, the actual translations represent a huge effort of many individuals, crippled by small technical difficulties. .PP Thankfully, Open Source software is actually very well translated using the gettext tool suite. These tools are used to extract the strings to translate from a program and present the strings to translate in a standardized format (called \s-1PO\s0 files, or translation catalogs). A whole ecosystem of tools has emerged to help the translators actually translate these \s-1PO\s0 files. The result is then used by gettext at run time to display translated messages to the end users. .PP 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. .PP Outdated translations are often worse than no translation at all. End-users can be tricked by documentation describing an old behavior of the program. Furthermore, they cannot interact directly with the maintainers since they don't speak English. Additionally, the maintainer cannot fix the problem as they don't know every language in which their documentation is translated. These difficulties, often caused by poor tooling, can undermine the motivation of volunteer translators, further aggravating the problem. .PP \&\fBThe goal of the po4a project is to ease the work of documentation translators\fR. In particular, it makes documentation translations \fImaintainable\fR. .PP The idea is to reuse and adapt the gettext approach to this field. As with gettext, texts are extracted from their original locations and presented to translators as \s-1PO\s0 translation catalogs. The translators can leverage the classical gettext tools to monitor the work to do, collaborate and organize as teams. po4a then injects the translations directly into the documentation structure to produce translated source files that can be processed and distributed just like the English files. Any paragraph that is not translated is left in English in the resulting document, ensuring that the end users never see an outdated translation in the documentation. .PP This automates most of the grunt work of the translation maintenance. Discovering the paragraphs needing an update becomes very easy, and the process is completely automated when elements are reordered without further modification. Specific verification can also be used to reduce the chance of formatting errors that would result in a broken document. .PP Please also see the \fB\s-1FAQ\s0\fR below in this document for a more complete list of the advantages and disadvantages of this approach. .SS "Supported formats" .IX Subsection "Supported formats" Currently, this approach has been successfully implemented to several kinds of text formatting formats: .IP "man (mature parser)" 4 .IX Item "man (mature parser)" The good old manual pages' format, used by so many programs out there. po4a support is very welcome here since this format is somewhat difficult to use and not really friendly to newbies. .Sp The \fBLocale::Po4a::Man\fR\|(3pm) module also supports the mdoc format, used by the \s-1BSD\s0 man pages (they are also quite common on Linux). .IP "AsciiDoc (mature parser)" 4 .IX Item "AsciiDoc (mature parser)" This format is a lightweight markup format intended to ease the authoring of documentation. It is for example used to document the git system. Those manpages are translated using po4a. .IP "pod (mature parser)" 4 .IX Item "pod (mature parser)" This is the Perl Online Documentation format. The language and extensions themselves are documented using this format in addition to most existing Perl scripts. It makes easy to keep the documentation close to the actual code by embedding them both in the same file. It makes programmer's life easier, but unfortunately, not the translator's, until you use po4a. .IP "sgml (mature parser)" 4 .IX Item "sgml (mature parser)" Even if superseded by \s-1XML\s0 nowadays, this format is still used for documents which are more than a few screens long. It can even be used for complete books. Documents of this length can be very challenging to update. \fBdiff\fR often reveals useless when the original text was re-indented after update. Fortunately, po4a can help you after that process. .Sp Currently, only DebianDoc and DocBook \s-1DTD\s0 are supported, but adding support for a new one is really easy. It is even possible to use po4a on an unknown \s-1SGML DTD\s0 without changing the code by providing the needed information on the command line. See \fBLocale::Po4a::Sgml\fR\|(3pm) for details. .IP "TeX / LaTeX (mature parser)" 4 .IX Item "TeX / LaTeX (mature parser)" The LaTeX format is a major documentation format used in the Free Software world and for publications. .Sp The \fBLocale::Po4a::LaTeX\fR\|(3pm) module was tested with the Python documentation, a book and some presentations. .IP "text (mature parser)" 4 .IX Item "text (mature parser)" The Text format is the base format for many formats that include long blocks of text, including Markdown, debian/changelog, and debian/control. .Sp This supports the common format used in Static Site Generators, READMEs, and other documentation systems. See \fBLocale::Po4a::Text\fR\|(3pm) for details. .IP "xml and \s-1XHMTL\s0 (probably mature parser)" 4 .IX Item "xml and XHMTL (probably mature parser)" The \s-1XML\s0 format is a base format for many documentation formats. .Sp Currently, the DocBook \s-1DTD\s0 (see \fBLocale::Po4a::Docbook\fR\|(3pm) for details) and \&\s-1XHTML\s0 are supported by po4a. .IP "texinfo (very highly experimental parser)" 4 .IX Item "texinfo (very highly experimental parser)" All of the \s-1GNU\s0 documentation is written in this format (it's even one of the requirements to become an official \s-1GNU\s0 project). The support for \&\fBLocale::Po4a::Texinfo\fR\|(3pm) in po4a is still at the beginning. Please report bugs and feature requests. .IP "Others supported formats" 4 .IX Item "Others supported formats" Po4a can also handle some more rare or specialized formats, such as the documentation of compilation options for the 2.4+ Linux kernels or the diagrams produced by the dia tool. Adding a new format is often very easy and the main task is to come up with a parser for your target format. See \&\fBLocale::Po4a::TransTractor\fR\|(3pm) for more information about this. .IP "Unsupported formats" 4 .IX Item "Unsupported formats" Unfortunately, po4a still lacks support for several documentation formats. Many of them would be easy to support in po4a. This includes formats not just used for documentation, such as, package descriptions (deb and rpm), package installation scripts questions, package changelogs, and all the specialized file formats used by programs such as game scenarios or wine resource files. .SH "Using po4a" .IX Header "Using po4a" Historically, po4a was built around four scripts, each fulfilling a specific task. \fBpo4a\-gettextize\fR\|(1) helps bootstrapping translations and optionally converting existing translation projects to po4a. \fBpo4a\-updatepo\fR\|(1) reflects the changes to the original documentation into the corresponding po files. \&\fBpo4a\-translate\fR\|(1) builds translated source file from the original file and the corresponding \s-1PO\s0 file. In addition, \fBpo4a\-normalize\fR\|(1) is mostly useful to debug the po4a parsers, as it produces an untranslated document from the original one. It makes it easier to spot the glitches introduced by the parsing process. .PP Most projects only require the features of \fBpo4a\-updatepo\fR\|(1) and \&\fBpo4a\-translate\fR\|(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 \s-1PO\s0 files up to date and build the documentation files correctly. As an answer, a all-in-one tool was provided: \fBpo4a\fR\|(1). This tool takes a configuration file describing the structure of the translation project: the location of the \s-1PO\s0 files, the list of files to translate, and the options to use, and it fully automatizes the process. When you invoke \fBpo4a\fR\|(1), it both updates the \s-1PO\s0 files and regenerate the translation files that need to. If everything is already up to date, \fBpo4a\fR\|(1) does not change any file. .PP The rest of this section gives an overview of how use the scripts' interface of po4a. Most users will probably prefer to use the all-in-one tool, that is described in the documentation of \fBpo4a\fR\|(1). .SS "Graphical overview of the po4a scripts" .IX Subsection "Graphical overview of the po4a scripts" The following schema gives an overview of how each po4a script can be used. Here, \fImaster.doc\fR is an example name for the documentation to be translated; \&\fI\s-1XX\s0.doc\fR is the same document translated in the language \s-1XX\s0 while \fIdoc.XX.po\fR is the translation catalog for that document in the \s-1XX\s0 language. Documentation authors will mostly be concerned with \fImaster.doc\fR (which can be a manpage, an \&\s-1XML\s0 document, an asciidoc file or similar); the translators will be mostly concerned with the \s-1PO\s0 file, while the end users will only see the \fI\s-1XX\s0.doc\fR file. .PP .Vb 10 \& 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\-updatepo] | \& 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\-translate] \& | \& V \& XX.doc \& (up\-to\-date) .Ve .PP This schema is complicated, but in practice only the right part (involving \&\fBpo4a\-updatepo\fR\|(1) and \fBpo4a\-translate\fR\|(1)) is used once the project is setup and configured. .PP The left part depicts how \fBpo4a\-gettextize\fR\|(1) can be used to convert an existing translation project to the po4a infrastructure. This script takes an original document and its translated counterpart, and tries to build the corresponding \s-1PO\s0 file. Such manual conversion is rather cumbersome (see the \&\fBpo4a\-gettextize\fR\|(1) documentation for more details), but it is only needed once to convert your existing translations. If you don't have any translation to convert, you can forget about this and focus on the right part of the schema. .PP On the top right part, the action of the original author is depicted, updating the documentation. The middle right part depicts the automatic actions of \&\fBpo4a\-updatepo\fR\|(1). 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 \*(L"fuzzy\*(R" marker indicating that the translation must be updated. New or heavily modified material is left untranslated. .PP Then, the \fImanual editing\fR reported depicts the action of the translators, that modify the \s-1PO\s0 files to provide translations to every original string and paragraph. This can be done using either a specific editor such as the \fB\s-1GNOME\s0 Translation Editor\fR, \s-1KDE\s0's \fBLokalize\fR or \fBpoedit\fR, or using an online localization platform such as \fBweblate\fR or \fBpootle\fR. The translation result is a set of \s-1PO\s0 files, one per language. Please refer to the gettext documentation for more details. .PP The bottom part of the figure shows how \fBpo4a\-translate\fR\|(1) creates a translated source document from the \fImaster.doc\fR original document and the \&\fIdoc.XX.po\fR 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. .PP As noted before, the \fBpo4a\fR\|(1) program combines the effects of the separated scripts, updating the \s-1PO\s0 files and the translated document in one invocation. The underlying logic remains the same. .SS "Starting a new translation" .IX Subsection "Starting a new translation" If you use \fBpo4a\fR\|(1), there is no specific step to start a translation. You just have to list the languages in the configuration file, and the missing \s-1PO\s0 files are automatically created. Naturally, the translator then have to provide translations for every content used in your documents. \fBpo4a\fR\|(1) also creates a \&\s-1POT\s0 file, that is a \s-1PO\s0 template file. Potential translators can translate your project into a new language by renaming this file and providing the translations in their language. .PP If you prefer to use the individual scripts separately, you should use \&\fBpo4a\-gettextize\fR\|(1) as follows to create the \s-1POT\s0 file. This file can then be copied into \fI\s-1XX\s0.po\fR to initiate a new translation. .PP .Vb 1 \& $ po4a\-gettextize \-\-format \-\-master \-\-po .Ve .PP The master document is used in input, while the \s-1POT\s0 file is the output of this process. .SS "Integrating changes to the original document" .IX Subsection "Integrating changes to the original document" The script to use for that is \fBpo4a\-updatepo\fR\|(1) (please refer to its documentation for details): .PP .Vb 1 \& $ po4a\-updatepo \-\-format \-\-master \-\-po .Ve .PP The master document is used in input, while the \s-1PO\s0 file is updated: it is used both in input and output. .SS "Generating a translated document" .IX Subsection "Generating a translated document" Once you're done with the translation, you want to get the translated documentation and distribute it to users along with the original one. For that, use the \fBpo4a\-translate\fR\|(1) program as follows: .PP .Vb 1 \& $ po4a\-translate \-\-format \-\-master \-\-po \-\-localized .Ve .PP Both the master and \s-1PO\s0 files are used in input, while the localized file is the output of this process. .SS "Using addenda to add extra text to translations" .IX Subsection "Using addenda to add extra text to translations" Adding new text to the translation is probably the only thing that is easier in the long run when you translate files manually :). This happens when you want to add an extra section to the translated document, not corresponding to any content in the original document. The classical use case is to give credits to the translation team, and to indicate how to report translation-specific issues. .PP With po4a, you have to specify \fBaddendum\fR files, that can be conceptually viewed as patches applied to the localized document after processing. Each addendum must be provided as a separate file, which format is however very different from the classical patches. The first line is a \fIheader line\fR, defining the insertion point of the addendum (with an unfortunately cryptic syntax \*(-- see below) while the rest of the file is added verbatim at the determined position. .PP The header line must begin with the string \fB\s-1PO4A\-HEADER:\s0\fR, followed by a semi-colon separated list of \fIkey\fR\fB=\fR\fIvalue\fR fields. .PP For example, the following header declares an addendum that must be placed at the very end of the translation. .PP .Vb 1 \& PO4A\-HEADER: mode=eof .Ve .PP Things are more complex when you want to add your extra content in the middle of the document. The following header declares an addendum that must be placed after the \s-1XML\s0 section containing the string \f(CW\*(C`About this document\*(C'\fR in translation. .PP .Vb 1 \& PO4A\-HEADER: position=About this document; mode=after; endboundary= .Ve .PP In practice, when trying to apply an addendum, po4a searches for the first line matching the \f(CW\*(C`position\*(C'\fR argument (this can be a regexp). Do not forget that po4a considers the \fBtranslated\fR document here. This documentation is in English, but your line should probably read as follows if you intend your addendum to apply to the French translation of the document. .PP .Vb 1 \& PO4A\-HEADER: position=À propos de ce document; mode=after; endboundary= .Ve .PP Once the \f(CW\*(C`position\*(C'\fR is found in the target document, po4a searches for the next line after the \f(CW\*(C`position\*(C'\fR that matches the provided \f(CW\*(C`endboundary\*(C'\fR. The addendum is added right \fBafter\fR that line (because we provided an \&\fIendboundary\fR, i.e. a boundary ending the current section). .PP The exact same effect could be obtained with the following header, that is equivalent: .PP .Vb 1 \& PO4A\-HEADER: position=About this document; mode=after; beginboundary=
.Ve .PP Here, po4a searches for the first line matching \f(CW\*(C` after the line matching \f(CW\*(C`About this document\*(C'\fR in the translation, and add the addendum \&\fBbefore\fR that line since we provided a \fIbeginboundary\fR, i.e. a boundary marking the beginning of the next section. So this header line requires to place the addendum after the section containing \f(CW\*(C`About this document\*(C'\fR, and instruct po4a that a section starts with a line containing the \f(CW\*(C` tag. This is equivalent to the previous example because what you really want is to add this addendum either after \f(CW\*(C`/section\*(C'\fR> or before \f(CW\*(C`. .PP You can also set the insertion \fImode\fR to the value \f(CW\*(C`before\*(C'\fR, with a similar semantic: combining \f(CW\*(C`mode=before\*(C'\fR with an \f(CW\*(C`endboundary\*(C'\fR will put the addendum just \fBafter\fR the matched boundary, that the last potential boundary line before the \f(CW\*(C`position\*(C'\fR. Combining \f(CW\*(C`mode=before\*(C'\fR with an \f(CW\*(C`beginboundary\*(C'\fR will put the addendum just \fBbefore\fR the matched boundary, that the last potential boundary line before the \f(CW\*(C`position\*(C'\fR. .PP .Vb 7 \& Mode | Boundary kind | Used boundary | Insertion point compared to the boundary \& ========|===============|========================|========================================= \& \*(Aqbefore\*(Aq| \*(Aqendboundary\*(Aq | last before \*(Aqposition\*(Aq | Right after the selected boundary \& \*(Aqbefore\*(Aq|\*(Aqbeginboundary\*(Aq| last before \*(Aqposition\*(Aq | Right before the selected boundary \& \*(Aqafter\*(Aq | \*(Aqendboundary\*(Aq | first after \*(Aqposition\*(Aq | Right after the selected boundary \& \*(Aqafter\*(Aq |\*(Aqbeginboundary\*(Aq| first after \*(Aqposition\*(Aq | Right before the selected boundary \& \*(Aqeof\*(Aq | (none) | n/a | End of file .Ve .PP \fIHint and tricks about addenda\fR .IX Subsection "Hint and tricks about addenda" .IP "\(bu" 4 Remember that these are regexp. For example, if you want to match the end of a nroff section ending with the line \f(CW\*(C`.fi\*(C'\fR, do not use \f(CW\*(C`.fi\*(C'\fR as \fBendboundary\fR, because it will match with \f(CW\*(C`the[ fi]le\*(C'\fR, which is obviously not what you expect. The correct \fBendboundary\fR in that case is: \f(CW\*(C`^\e.fi$\*(C'\fR. .IP "\(bu" 4 White spaces \s-1ARE\s0 important in the content of the \f(CW\*(C`position\*(C'\fR and boundaries. So the two following lines \fBare different\fR. The second one will only be found if there is enough trailing spaces in the translated document. .Sp .Vb 2 \& PO4A\-HEADER: position=About this document; mode=after; beginboundary=
\& PO4A\-HEADER: position=About this document ; mode=after; beginboundary=
.Ve .IP "\(bu" 4 Although this context search may be considered to operate roughly on each line of the \fBtranslated\fR document, it actually operates on the internal data string of the translated document. This internal data string may be a text spanning a paragraph containing multiple lines or may be a \s-1XML\s0 tag itself alone. The exact \fIinsertion point\fR of the addendum must be before or after the internal data string and can not be within the internal data string. .IP "\(bu" 4 Pass the \fB\-vv\fR argument to po4a to understand how the addenda are added to the translation. It may also help to run po4a in debug mode to see the actual internal data string when your addendum does not apply. .PP \fIAddenda examples\fR .IX Subsection "Addenda examples" .IP "\(bu" 4 If you want to add something after the following nroff section: .Sp .Vb 1 \& .SH "AUTHORS" .Ve .Sp You should select a two step approach by setting \fBmode=after\fR. Then you should narrow down search to the line after \fB\s-1AUTHORS\s0\fR with the \fBposition\fR argument regex. Then, you should match the beginning of the next section (i.e., \&\fB^\e.SH\fR) with the \fBbeginboundary\fR argument regex. That is to say: .Sp .Vb 1 \& PO4A\-HEADER:mode=after;position=AUTHORS;beginboundary=\e.SH .Ve .IP "\(bu" 4 If you want to add something right after a given line (e.g. after the line \&\*(L"Copyright Big Dude\*(R"), use a \fBposition\fR matching this line, \fBmode=after\fR and give a \fBbeginboundary\fR matching any line. .Sp .Vb 1 \& PO4A\-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^ .Ve .IP "\(bu" 4 If you want to add something at the end of the document, give a \fBposition\fR matching any line of your document (but only one line. Po4a won't proceed if it's not unique), and give an \fBendboundary\fR matching nothing. Don't use simple strings here like \fB\*(L"\s-1EOF\*(R"\s0\fR, but prefer those which have less chance to be in your document. .Sp .Vb 1 \& PO4A\-HEADER:mode=after;position=About this document;beginboundary=FakePo4aBoundary .Ve .PP \fIMore detailed example\fR .IX Subsection "More detailed example" .PP Original document (\s-1POD\s0 formatted): .PP .Vb 7 \& |=head1 NAME \& | \& |dummy \- a dummy program \& | \& |=head1 AUTHOR \& | \& |me .Ve .PP Then, the following addendum will ensure that a section (in French) about the translator is added at the end of the file (in French, \*(L"\s-1TRADUCTEUR\*(R"\s0 means \*(L"\s-1TRANSLATOR\*(R",\s0 and \*(L"moi\*(R" means \*(L"me\*(R"). .PP .Vb 6 \& |PO4A\-HEADER:mode=after;position=AUTEUR;beginboundary=^=head \& | \& |=head1 TRADUCTEUR \& | \& |moi \& | .Ve .PP To put your addendum before the \s-1AUTHOR,\s0 use the following header: .PP .Vb 1 \& PO4A\-HEADER:mode=after;position=NOM;beginboundary=^=head1 .Ve .PP This works because the next line matching the \fBbeginboundary\fR /^=head1/ after the section \*(L"\s-1NAME\*(R"\s0 (translated to \*(L"\s-1NOM\*(R"\s0 in French), is the one declaring the authors. So, the addendum will be put between both sections. Note that if another section is added between \s-1NAME\s0 and \s-1AUTHOR\s0 sections later, po4a will wrongfully put the addenda before the new section. .PP To avoid this you may accomplish the same using \fBmode\fR=\fIbefore\fR: .PP .Vb 1 \& PO4A\-HEADER:mode=before;position=^=head1 AUTEUR .Ve .SH "How does it work?" .IX Header "How does it work?" This chapter gives you a brief overview of the po4a internals, so that you may feel more confident to help us maintaining and improving it. It may also help you understanding why it does not do what you expected, and how to solve your problems. .PP The po4a architecture is object oriented. The \&\fBLocale::Po4a::TransTractor\fR\|(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. .PP More formally, it takes a document to translate plus a \s-1PO\s0 file containing the translations to use as input while producing two separate outputs: Another \s-1PO\s0 file (resulting of the extraction of translatable strings from the input document), and a translated document (with the same structure than the input one, but with all translatable strings replaced with content of the input \s-1PO\s0). Here is a graphical representation of this: .PP .Vb 6 \& Input document \-\-\e /\-\-\-> Output document \& \e TransTractor:: / (translated) \& +\-\->\-\- parse() \-\-\-\-\-\-\-\-+ \& / \e \& Input PO \-\-\-\-\-\-\-\-/ \e\-\-\-> Output PO \& (extracted) .Ve .PP This little bone is the core of all the po4a architecture. If you omit the input \&\s-1PO\s0 and the output document, you get \fBpo4a\-gettextize\fR. If you provide both input and disregard the output \s-1PO,\s0 you get \fBpo4a\-translate\fR. The \fBpo4a\fR calls TransTractor twice and calls \fBmsgmerge \-U\fR between these TransTractor invocations to provide one-stop solution with a single configuration file. Please see \fBLocale::Po4a::TransTractor\fR\|(3pm) for more details. .SH "Open-source projects using po4a" .IX Header "Open-source projects using po4a" Here is a very partial list of projects that use po4a in production for their documentation. If you want to add your project to the list, just drop us an email (or a Merge Request). .IP "\(bu" 4 adduser (man): users and groups management tool. .IP "\(bu" 4 apt (man, docbook): Debian package manager. .IP "\(bu" 4 aptitude (docbook, svg): terminal-based package manager for Debian .IP "\(bu" 4 F\-Droid website (markdown): installable catalogue of \s-1FOSS\s0 (Free and Open Source Software) applications for the Android platform. .IP "\(bu" 4 git (asciidoc): distributed version-control system for tracking changes in source code. .IP "\(bu" 4 Linux manpages (man) .Sp This project provides an infrastructure for translating many manpages to different languages, ready for integration into several major distributions (Arch Linux, Debian and derivatives, Fedora). .IP "\(bu" 4 Stellarium (\s-1HTML\s0): a free open source planetarium for your computer. po4a is used to translate the sky culture descriptions. .SH "FAQ" .IX Header "FAQ" .SS "How do you pronounce po4a?" .IX Subsection "How do you pronounce po4a?" I personally vocalize it as pouah , which is a French onomatopoetic that we use in place of yuck :) I may have a strange sense of humor :) .SS "What about the other translation tools for documentation using gettext?" .IX Subsection "What about the other translation tools for documentation using gettext?" As far as I know, there are only two of them: .IP "\fBpoxml\fR" 4 .IX Item "poxml" This is the tool developed by \s-1KDE\s0 people to handle DocBook \s-1XML. AFAIK,\s0 it was the first program to extract strings to translate from documentation to \&\s-1PO\s0 files, and inject them back after translation. .Sp It can only handle \s-1XML,\s0 and only a particular \s-1DTD. I\s0'm quite unhappy with the handling of lists, which end in one big msgid. When the list become big, the chunk becomes harder to swallow. .IP "\fBpo-debiandoc\fR" 4 .IX Item "po-debiandoc" This program done by Denis Barbier is a sort of precursor of the po4a \s-1SGML\s0 module, which more or less deprecates it. As the name says, it handles only the DebianDoc \s-1DTD,\s0 which is more or less a deprecated \s-1DTD.\s0 .PP The main advantages of po4a over them are the ease of extra content addition (which is even worse there) and the ability to achieve gettextization. .SS "\s-1SUMMARY\s0 of the advantages of the gettext based approach" .IX Subsection "SUMMARY of the advantages of the gettext based approach" .IP "\(bu" 2 The translations are not stored along with the original, which makes it possible to detect if translations become out of date. .IP "\(bu" 2 The translations are stored in separate files from each other, which prevents translators of different languages from interfering, both when submitting their patch and at the file encoding level. .IP "\(bu" 2 It is based internally on \fBgettext\fR (but \fBpo4a\fR offers a very simple interface so that you don't need to understand the internals to use it). That way, we don't have to re-implement the wheel, and because of their wide use, we can think that these tools are more or less bug free. .IP "\(bu" 2 Nothing changed for the end-user (beside the fact translations will hopefully be better maintained). The resulting documentation file distributed is exactly the same. .IP "\(bu" 2 No need for translators to learn a new file syntax and their favorite \s-1PO\s0 file editor (like Emacs' \s-1PO\s0 mode, Lokalize or Gtranslator) will work just fine. .IP "\(bu" 2 gettext offers a simple way to get statistics about what is done, what should be reviewed and updated, and what is still to do. Some example can be found at those addresses: .Sp .Vb 2 \& \- https://docs.kde.org/stable5/en/kdesdk/lokalize/project\-view.html \& \- http://www.debian.org/intl/l10n/ .Ve .PP But everything isn't green, and this approach also has some disadvantages we have to deal with. .IP "\(bu" 2 Addenda are… strange at the first glance. .IP "\(bu" 2 You can't adapt the translated text to your preferences, like splitting a paragraph here, and joining two other ones there. But in some sense, if there is an issue with the original, it should be reported as a bug anyway. .IP "\(bu" 2 Even with an easy interface, it remains a new tool people have to learn. .Sp One of my dreams would be to integrate somehow po4a to Gtranslator or Lokalize. When a documentation file is opened, the strings are automatically extracted, and a translated file + po file can be written to disk. If we manage to do an \s-1MS\s0 Word (\s-1TM\s0) module (or at least \s-1RTF\s0) professional translators may even use it. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 The documentation of the all-in-one tool that you should use: \fBpo4a\fR\|(1). .IP "\(bu" 4 The documentation of the individual po4a scripts: \fBpo4a\-gettextize\fR\|(1), \&\fBpo4a\-updatepo\fR\|(1), \fBpo4a\-translate\fR\|(1), \fBpo4a\-normalize\fR\|(1). .IP "\(bu" 4 The additional helping scripts: \&\fBmsguntypot\fR\|(1), \fBpo4a\-display\-man\fR\|(1), \fBpo4a\-display\-pod\fR\|(1). .IP "\(bu" 4 The parsers of each formats, in particular to see the options accepted by each of them: \fBLocale::Po4a::AsciiDoc\fR\|(3pm) \fBLocale::Po4a::Dia\fR\|(3pm), \&\fBLocale::Po4a::Guide\fR\|(3pm), \fBLocale::Po4a::Ini\fR\|(3pm), \&\fBLocale::Po4a::KernelHelp\fR\|(3pm), \fBLocale::Po4a::Man\fR\|(3pm), \&\fBLocale::Po4a::RubyDoc\fR\|(3pm), \fBLocale::Po4a::Texinfo\fR\|(3pm), \&\fBLocale::Po4a::Text\fR\|(3pm), \fBLocale::Po4a::Xhtml\fR\|(3pm), \&\fBLocale::Po4a::Yaml\fR\|(3pm), \fBLocale::Po4a::BibTeX\fR\|(3pm), \&\fBLocale::Po4a::Docbook\fR\|(3pm), \fBLocale::Po4a::Halibut\fR\|(3pm), \&\fBLocale::Po4a::LaTeX\fR\|(3pm), \fBLocale::Po4a::Pod\fR\|(3pm), \&\fBLocale::Po4a::Sgml\fR\|(3pm), \fBLocale::Po4a::TeX\fR\|(3pm), \&\fBLocale::Po4a::Wml\fR\|(3pm), \fBLocale::Po4a::Xml\fR\|(3pm). .IP "\(bu" 4 The implementation of the core infrastructure: \&\fBLocale::Po4a::TransTractor\fR\|(3pm) (particularly important to understand the code organization), \fBLocale::Po4a::Chooser\fR\|(3pm), \fBLocale::Po4a::Po\fR\|(3pm), \&\fBLocale::Po4a::Common\fR\|(3pm). Please also check the \fI\s-1CONTRIBUTING\s0.md\fR file in the source tree. .SH "AUTHORS" .IX Header "AUTHORS" .Vb 2 \& Denis Barbier \& Martin Quinson (mquinson#debian.org) .Ve