1PO4A(7) Po4a Tools PO4A(7)
2
6 po4a - framework to translate documentation and other materials
7
9 po4a (PO for anything) eases the maintenance of documentation
10 translation using the classical gettext tools. The main feature of po4a
11 is that it decouples the translation of content from its document
12 structure.
13 This document serves as an introduction to the po4a project with a
15 focus on potential users considering whether to use this tool and on
16 the curious wanting to understand why things are the way they are.
17
19 The philosophy of Free Software is to make the technology truly
20 available to everyone. But licensing is not the only consideration:
21 untranslated free software is useless for non-English speakers.
22 Therefore, we still have some work to do to make software available to
23 everybody.
24 This situation is well understood by most projects and everybody is now
26 convinced of the necessity to translate everything. Yet, the actual
27 translations represent a huge effort of many individuals, crippled by
28 small technical difficulties.
29 Thankfully, Open Source software is actually very well translated using
31 the gettext tool suite. These tools are used to extract the strings to
32 translate from a program and present the strings to translate in a
33 standardized format (called PO files, or translation catalogs). A whole
34 ecosystem of tools has emerged to help the translators actually
35 translate these PO files. The result is then used by gettext at run
36 time to display translated messages to the end users.
37 Regarding documentation, however, the situation still somewhat
39 disappointing. At first translating documentation may seem to be
40 easier than translating a program as it would seem that you just have
41 to copy the documentation source file and start translating the
42 content. However, when the original documentation is modified, keeping
43 track of the modifications quickly turns into a nightmare for the
44 translators. If done manually, this task is unpleasant and error prone.
45 Outdated translations are often worse than no translation at all. End-
47 users can be tricked by documentation describing an old behavior of the
48 program. Furthermore, they cannot interact directly with the
49 maintainers since they don't speak English. Additionally, the
50 maintainer cannot fix the problem as they don't know every language in
51 which their documentation is translated. These difficulties, often
52 caused by poor tooling, can undermine the motivation of volunteer
53 translators, further aggravating the problem.
54 The goal of the po4a project is to ease the work of documentation
56 translators. In particular, it makes documentation translations
57 maintainable.
58 The idea is to reuse and adapt the gettext approach to this field. As
60 with gettext, texts are extracted from their original locations and
61 presented to translators as PO translation catalogs. The translators
62 can leverage the classical gettext tools to monitor the work to do,
63 collaborate and organize as teams. po4a then injects the translations
64 directly into the documentation structure to produce translated source
65 files that can be processed and distributed just like the English
66 files. Any paragraph that is not translated is left in English in the
67 resulting document, ensuring that the end users never see an outdated
68 translation in the documentation.
69 This automates most of the grunt work of the translation maintenance.
71 Discovering the paragraphs needing an update becomes very easy, and the
72 process is completely automated when elements are reordered without
73 further modification. Specific verification can also be used to reduce
74 the chance of formatting errors that would result in a broken document.
75 Please also see the FAQ below in this document for a more complete list
77 of the advantages and disadvantages of this approach.
78 Supported formats
80 Currently, this approach has been successfully implemented to several
81 kinds of text formatting formats:
82 man (mature parser)
84 The good old manual pages' format, used by so many programs out
85 there. po4a support is very welcome here since this format is
86 somewhat difficult to use and not really friendly to newbies.
87 The Locale::Po4a::Man(3pm) module also supports the mdoc format,
89 used by the BSD man pages (they are also quite common on Linux).
90 AsciiDoc (mature parser)
92 This format is a lightweight markup format intended to ease the
93 authoring of documentation. It is for example used to document the
94 git system. Those manpages are translated using po4a.
95 See Locale::Po4a::AsciiDoc for details.
97 pod (mature parser)
99 This is the Perl Online Documentation format. The language and
100 extensions themselves are documented using this format in addition
101 to most existing Perl scripts. It makes easy to keep the
102 documentation close to the actual code by embedding them both in
103 the same file. It makes programmer's life easier, but
104 unfortunately, not the translator's, until you use po4a.
105 See Locale::Po4a::Pod for details.
107 sgml (mature parser)
109 Even if superseded by XML nowadays, this format is still used for
110 documents which are more than a few screens long. It can even be
111 used for complete books. Documents of this length can be very
112 challenging to update. diff often reveals useless when the original
113 text was re-indented after update. Fortunately, po4a can help you
114 after that process.
115 Currently, only DebianDoc and DocBook DTD are supported, but adding
117 support for a new one is really easy. It is even possible to use
118 po4a on an unknown SGML DTD without changing the code by providing
119 the needed information on the command line. See
120 Locale::Po4a::Sgml(3pm) for details.
121 TeX / LaTeX (mature parser)
123 The LaTeX format is a major documentation format used in the Free
124 Software world and for publications.
125 The Locale::Po4a::LaTeX(3pm) module was tested with the Python
127 documentation, a book and some presentations.
128 text (mature parser)
130 The Text format is the base format for many formats that include
131 long blocks of text, including Markdown, fortunes, YAML front
132 matter section, debian/changelog, and debian/control.
133 This supports the common format used in Static Site Generators,
135 READMEs, and other documentation systems. See
136 Locale::Po4a::Text(3pm) for details.
137 xml and XHMTL (probably mature parser)
139 The XML format is a base format for many documentation formats.
140 Currently, the DocBook DTD (see Locale::Po4a::Docbook(3pm) for
142 details) and XHTML are supported by po4a.
143 BibTex (probably mature parser)
145 The BibTex format is used alongside LaTex for formatting lists of
146 references (bibliographies).
147 See Locale::Po4a::BibTex for details.
149 Docbook (probably mature parser)
151 A XML-based markup language that uses semantic tags to describe
152 documents.
153 See Locale::Po4a:Docbook for greater details.
155 Guide XML (probably mature parser)
157 A XML documentation format. This module was developed specifically
158 to help with supporting and maintaining translations of Gentoo
159 Linux documentation up until at least March 2016 (Based on the
160 Wayback Machine). Gentoo have since moved to the DevBook XML
161 format.
162 See Locale::Po4a:Guide for greater details.
164 Wml (probably mature parser)
166 The Web Markup Language, do not mixup WML with the WAP stuff used
167 on cell phones. This module relies on the Xhtml module, which
168 itself relies on the XmL module.
169 See Locale::Po4a::Wml for greater details.
171 Yaml (probably mature parser)
173 A strict superset of JSON. YAML is often used as systems or
174 configuration projects. YAML is at the core of Red Hat's Ansible.
175 See Locale::Po4a::Yaml for greater details.
177 RubyDoc (probably mature parser)
179 The Ruby Document (RD) format, originally the default documentation
180 format for Ruby and Ruby projects before converted to RDoc in 2002.
181 Though apparently the Japanese version of the Ruby Reference Manual
182 still use RD.
183 See Locale::Po4a::RubyDoc for greater details.
185 Halibut (probably experimental parser)
187 A documentation production system, with elements similar to TeX,
188 debiandoc-sgml, TeXinfo, and others, developed by Simon Tatham, the
189 developer of PuTTY.
190 See Locale::Po4a:Halibut for greater details.
192 Ini (probably experimental parser)
194 Configuration file format popularized by MS-DOS.
195 See Locale::Po4a::Ini for greater details.
197 texinfo (very highly experimental parser)
199 All of the GNU documentation is written in this format (it's even
200 one of the requirements to become an official GNU project). The
201 support for Locale::Po4a::Texinfo(3pm) in po4a is still at the
202 beginning. Please report bugs and feature requests.
203 Others supported formats
205 Po4a can also handle some more rare or specialized formats, such as
206 the documentation of compilation options for the 2.4+ Linux kernels
207 (Locale::Po4a::KernelHelp) or the diagrams produced by the dia tool
208 (Locale::Po4a:Dia). Adding a new format is often very easy and the
209 main task is to come up with a parser for your target format. See
210 Locale::Po4a::TransTractor(3pm) for more information about this.
211 Unsupported formats
213 Unfortunately, po4a still lacks support for several documentation
214 formats. Many of them would be easy to support in po4a. This
215 includes formats not just used for documentation, such as, package
216 descriptions (deb and rpm), package installation scripts questions,
217 package changelogs, and all the specialized file formats used by
218 programs such as game scenarios or wine resource files.
219
221 Historically, po4a was built around four scripts, each fulfilling a
222 specific task. po4a-gettextize(1) helps bootstrapping translations and
223 optionally converting existing translation projects to po4a.
224 po4a-updatepo(1) reflects the changes to the original documentation
225 into the corresponding po files. po4a-translate(1) builds translated
226 source file from the original file and the corresponding PO file. In
227 addition, po4a-normalize(1) is mostly useful to debug the po4a parsers,
228 as it produces an untranslated document from the original one. It makes
229 it easier to spot the glitches introduced by the parsing process.
230 Most projects only require the features of po4a-updatepo(1) and
232 po4a-translate(1), but these scripts proved to be cumbersome and error
233 prone to use. If the documentation to translate is split over several
234 source files, it is difficult to keep the PO files up to date and build
235 the documentation files correctly. As an answer, a all-in-one tool was
236 provided: po4a(1). This tool takes a configuration file describing the
237 structure of the translation project: the location of the PO files, the
238 list of files to translate, and the options to use, and it fully
239 automates the process. When you invoke po4a(1), it both updates the PO
240 files and regenerate the translation files that need to. If everything
241 is already up to date, po4a(1) does not change any file.
242 The rest of this section gives an overview of how use the scripts'
244 interface of po4a. Most users will probably prefer to use the all-in-
245 one tool, that is described in the documentation of po4a(1).
246 Graphical overview of the po4a scripts
248 The following schema gives an overview of how each po4a script can be
249 used. Here, master.doc is an example name for the documentation to be
250 translated; XX.doc is the same document translated in the language XX
251 while doc.XX.po is the translation catalog for that document in the XX
252 language. Documentation authors will mostly be concerned with
253 master.doc (which can be a manpage, an XML document, an asciidoc file
254 or similar); the translators will be mostly concerned with the PO file,
255 while the end users will only see the XX.doc file.
256 master.doc
258 |
259 V
260 +<-----<----+<-----<-----<--------+------->-------->-------+
261 : | | :
262 {translation} | { update of master.doc } :
263 : | | :
264 XX.doc | V V
265 (optional) | master.doc ->-------->------>+
266 : | (new) |
267 V V | |
268 [po4a-gettextize] doc.XX.po -->+ | |
269 | (old) | | |
270 | ^ V V |
271 | | [po4a-updatepo] |
272 V | | V
273 translation.pot ^ V |
274 | | doc.XX.po |
275 | | (fuzzy) |
276 { translation } | | |
277 | ^ V V
278 | | {manual editing} |
279 | | | |
280 V | V V
281 doc.XX.po --->---->+<---<-- doc.XX.po addendum master.doc
282 (initial) (up-to-date) (optional) (up-to-date)
283 : | | |
284 : V | |
285 +----->----->----->------> + | |
286 | | |
287 V V V
288 +------>-----+------<------+
289 |
290 V
291 [po4a-translate]
292 |
293 V
294 XX.doc
295 (up-to-date)
296 This schema is complicated, but in practice only the right part
298 (involving po4a-updatepo(1) and po4a-translate(1)) is used once the
299 project is setup and configured.
300 The left part depicts how po4a-gettextize(1) can be used to convert an
302 existing translation project to the po4a infrastructure. This script
303 takes an original document and its translated counterpart, and tries to
304 build the corresponding PO file. Such manual conversion is rather
305 cumbersome (see the po4a-gettextize(1) documentation for more details),
306 but it is only needed once to convert your existing translations. If
307 you don't have any translation to convert, you can forget about this
308 and focus on the right part of the schema.
309 On the top right part, the action of the original author is depicted,
311 updating the documentation. The middle right part depicts the automatic
312 actions of po4a-updatepo(1). The new material is extracted and compared
313 against the exiting translation. The previous translation is used for
314 the parts that didn't change, while partially modified parts are
315 connected to the previous translation with a "fuzzy" marker indicating
316 that the translation must be updated. New or heavily modified material
317 is left untranslated.
318 Then, the manual editing reported depicts the action of the
320 translators, that modify the PO files to provide translations to every
321 original string and paragraph. This can be done using either a specific
322 editor such as the GNOME Translation Editor, KDE's Lokalize or poedit,
323 or using an online localization platform such as weblate or pootle. The
324 translation result is a set of PO files, one per language. Please refer
325 to the gettext documentation for more details.
326 The bottom part of the figure shows how po4a-translate(1) creates a
328 translated source document from the master.doc original document and
329 the doc.XX.po translation catalog that was updated by the translators.
330 The structure of the document is reused, while the original content is
331 replaced by its translated counterpart. Optionally, an addendum can be
332 used to add some extra text to the translation. This is often used to
333 add the name of the translator to the final document. See below for
334 details.
335 As noted before, the po4a(1) program combines the effects of the
337 separated scripts, updating the PO files and the translated document in
338 one invocation. The underlying logic remains the same.
339 Starting a new translation
341 If you use po4a(1), there is no specific step to start a translation.
342 You just have to list the languages in the configuration file, and the
343 missing PO files are automatically created. Naturally, the translator
344 then have to provide translations for every content used in your
345 documents. po4a(1) also creates a POT file, that is a PO template file.
346 Potential translators can translate your project into a new language by
347 renaming this file and providing the translations in their language.
348 If you prefer to use the individual scripts separately, you should use
350 po4a-gettextize(1) as follows to create the POT file. This file can
351 then be copied into XX.po to initiate a new translation.
352 $ po4a-gettextize --format <format> --master <master.doc> --po <translation.pot>
354 The master document is used in input, while the POT file is the output
356 of this process.
357 Integrating changes to the original document
359 The script to use for that is po4a-updatepo(1) (please refer to its
360 documentation for details):
361 $ po4a-updatepo --format <format> --master <new_master.doc> --po <old_doc.XX.po>
363 The master document is used in input, while the PO file is updated: it
365 is used both in input and output.
366 Generating a translated document
368 Once you're done with the translation, you want to get the translated
369 documentation and distribute it to users along with the original one.
370 For that, use the po4a-translate(1) program as follows:
371 $ po4a-translate --format <format> --master <master.doc> --po <doc.XX.po> --localized <XX.doc>
373 Both the master and PO files are used in input, while the localized
375 file is the output of this process.
376 Using addenda to add extra text to translations
378 Adding new text to the translation is probably the only thing that is
379 easier in the long run when you translate files manually :). This
380 happens when you want to add an extra section to the translated
381 document, not corresponding to any content in the original document.
382 The classical use case is to give credits to the translation team, and
383 to indicate how to report translation-specific issues.
384 With po4a, you have to specify addendum files, that can be conceptually
386 viewed as patches applied to the localized document after processing.
387 Each addendum must be provided as a separate file, which format is
388 however very different from the classical patches. The first line is a
389 header line, defining the insertion point of the addendum (with an
390 unfortunately cryptic syntax -- see below) while the rest of the file
391 is added verbatim at the determined position.
392 The header line must begin with the string PO4A-HEADER:, followed by a
394 semi-colon separated list of key=value fields.
395 For example, the following header declares an addendum that must be
397 placed at the very end of the translation.
398 PO4A-HEADER: mode=eof
400 Things are more complex when you want to add your extra content in the
402 middle of the document. The following header declares an addendum that
403 must be placed after the XML section containing the string "About this
404 document" in translation.
405 PO4A-HEADER: position=About this document; mode=after; endboundary=</section>
407 In practice, when trying to apply an addendum, po4a searches for the
409 first line matching the "position" argument (this can be a regexp). Do
410 not forget that po4a considers the translated document here. This
411 documentation is in English, but your line should probably read as
412 follows if you intend your addendum to apply to the French translation
413 of the document.
414 PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>
416 Once the "position" is found in the target document, po4a searches for
418 the next line after the "position" that matches the provided
419 "endboundary". The addendum is added right after that line (because we
420 provided an endboundary, i.e. a boundary ending the current section).
421 The exact same effect could be obtained with the following header, that
423 is equivalent:
424 PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>
426 Here, po4a searches for the first line matching "<section"> after the
428 line matching "About this document" in the translation, and add the
429 addendum before that line since we provided a beginboundary, i.e. a
430 boundary marking the beginning of the next section. So this header line
431 requires to place the addendum after the section containing "About this
432 document", and instruct po4a that a section starts with a line
433 containing the "<section"> tag. This is equivalent to the previous
434 example because what you really want is to add this addendum either
435 after "/section"> or before "<section">.
436 You can also set the insertion mode to the value "before", with a
438 similar semantic: combining "mode=before" with an "endboundary" will
439 put the addendum just after the matched boundary, that the last
440 potential boundary line before the "position". Combining "mode=before"
441 with an "beginboundary" will put the addendum just before the matched
442 boundary, that the last potential boundary line before the "position".
443 Mode | Boundary kind | Used boundary | Insertion point compared to the boundary
445 ========|===============|========================|=========================================
446 'before'| 'endboundary' | last before 'position' | Right after the selected boundary
447 'before'|'beginboundary'| last before 'position' | Right before the selected boundary
448 'after' | 'endboundary' | first after 'position' | Right after the selected boundary
449 'after' |'beginboundary'| first after 'position' | Right before the selected boundary
450 'eof' | (none) | n/a | End of file
451 Hint and tricks about addenda
453 • Remember that these are regexp. For example, if you want to match
455 the end of a nroff section ending with the line ".fi", do not use
456 ".fi" as endboundary, because it will match with "the[ fi]le",
457 which is obviously not what you expect. The correct endboundary in
458 that case is: "^\.fi$".
459 • White spaces ARE important in the content of the "position" and
461 boundaries. So the two following lines are different. The second
462 one will only be found if there is enough trailing spaces in the
463 translated document.
464 PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>
466 PO4A-HEADER: position=About this document ; mode=after; beginboundary=<section>
467 • Although this context search may be considered to operate roughly
469 on each line of the translated document, it actually operates on
470 the internal data string of the translated document. This internal
471 data string may be a text spanning a paragraph containing multiple
472 lines or may be a XML tag itself alone. The exact insertion point
473 of the addendum must be before or after the internal data string
474 and can not be within the internal data string.
475 • Pass the -vv argument to po4a to understand how the addenda are
477 added to the translation. It may also help to run po4a in debug
478 mode to see the actual internal data string when your addendum does
479 not apply.
480 Addenda examples
482 • If you want to add something after the following nroff section:
484 .SH "AUTHORS"
486 You should select a two step approach by setting mode=after. Then
488 you should narrow down search to the line after AUTHORS with the
489 position argument regex. Then, you should match the beginning of
490 the next section (i.e., ^\.SH) with the beginboundary argument
491 regex. That is to say:
492 PO4A-HEADER:mode=after;position=AUTHORS;beginboundary=\.SH
494 • If you want to add something right after a given line (e.g. after
496 the line "Copyright Big Dude"), use a position matching this line,
497 mode=after and give a beginboundary matching any line.
498 PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^
500 • If you want to add something at the end of the document, give a
502 position matching any line of your document (but only one line.
503 Po4a won't proceed if it's not unique), and give an endboundary
504 matching nothing. Don't use simple strings here like "EOF", but
505 prefer those which have less chance to be in your document.
506 PO4A-HEADER:mode=after;position=About this document;beginboundary=FakePo4aBoundary
508 More detailed example
510 Original document (POD formatted):
512 |=head1 NAME
514 |
515 |dummy - a dummy program
516 |
517 |=head1 AUTHOR
518 |
519 |me
520 Then, the following addendum will ensure that a section (in French)
522 about the translator is added at the end of the file (in French,
523 "TRADUCTEUR" means "TRANSLATOR", and "moi" means "me").
524 |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
526 |
527 |=head1 TRADUCTEUR
528 |
529 |moi
530 |
531 To put your addendum before the AUTHOR, use the following header:
533 PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1
535 This works because the next line matching the beginboundary /^=head1/
537 after the section "NAME" (translated to "NOM" in French), is the one
538 declaring the authors. So, the addendum will be put between both
539 sections. Note that if another section is added between NAME and AUTHOR
540 sections later, po4a will wrongfully put the addenda before the new
541 section.
542 To avoid this you may accomplish the same using mode=before:
544 PO4A-HEADER:mode=before;position=^=head1 AUTEUR
546
548 This chapter gives you a brief overview of the po4a internals, so that
549 you may feel more confident to help us maintaining and improving it. It
550 may also help you understanding why it does not do what you expected,
551 and how to solve your problems.
552 The po4a architecture is object oriented. The
554 Locale::Po4a::TransTractor(3pm) class is the common ancestor to all
555 po4a parsers. This strange name comes from the fact that it is at the
556 same time in charge of translating document and extracting strings.
557 More formally, it takes a document to translate plus a PO file
559 containing the translations to use as input while producing two
560 separate outputs: Another PO file (resulting of the extraction of
561 translatable strings from the input document), and a translated
562 document (with the same structure than the input one, but with all
563 translatable strings replaced with content of the input PO). Here is a
564 graphical representation of this:
565 Input document --\ /---> Output document
567 \ TransTractor:: / (translated)
568 +-->-- parse() --------+
569 / \
570 Input PO --------/ \---> Output PO
571 (extracted)
572 This little bone is the core of all the po4a architecture. If you omit
574 the input PO and the output document, you get po4a-gettextize. If you
575 provide both input and disregard the output PO, you get po4a-translate.
576 The po4a calls TransTractor twice and calls msgmerge -U between these
577 TransTractor invocations to provide one-stop solution with a single
578 configuration file. Please see Locale::Po4a::TransTractor(3pm) for
579 more details.
580
582 Here is a very partial list of projects that use po4a in production for
583 their documentation. If you want to add your project to the list, just
584 drop us an email (or a Merge Request).
585 • adduser (man): users and groups management tool.
587 • apt (man, docbook): Debian package manager.
589 • aptitude (docbook, svg): terminal-based package manager for Debian
591 • F-Droid website <https://gitlab.com/fdroid/fdroid-website>
593 (markdown): installable catalogue of FOSS (Free and Open Source
594 Software) applications for the Android platform.
595 • git <https://github.com/jnavila/git-manpages-l10n> (asciidoc):
597 distributed version-control system for tracking changes in source
598 code.
599 • Linux manpages <https://salsa.debian.org/manpages-l10n-
601 team/manpages-l10n> (man)
602 This project provides an infrastructure for translating many
604 manpages to different languages, ready for integration into several
605 major distributions (Arch Linux, Debian and derivatives, Fedora).
606 • Stellarium <https://github.com/Stellarium/stellarium> (HTML): a
608 free open source planetarium for your computer. po4a is used to
609 translate the sky culture descriptions.
610 • Other item to sort out: <https://gitlab.com/fdroid/fdroid-website/>
612 <https://github.com/fsfe/reuse-docs/pull/61>
613
615 How do you pronounce po4a?
616 I personally vocalize it as pouah
617 <https://en.wiktionary.org/wiki/pouah>, which is a French onomatopoetic
618 that we use in place of yuck :) I may have a strange sense of humor :)
619 What about the other translation tools for documentation using gettext?
621 There are a few of them. Here is a possibly incomplete list, and more
622 tools are coming at the horizon.
623 poxml
625 This is the tool developed by KDE people to handle DocBook XML.
626 AFAIK, it was the first program to extract strings to translate
627 from documentation to PO files, and inject them back after
628 translation.
629 It can only handle XML, and only a particular DTD. I'm quite
631 unhappy with the handling of lists, which end in one big msgid.
632 When the list become big, the chunk becomes harder to swallow.
633 po-debiandoc
635 This program done by Denis Barbier is a sort of precursor of the
636 po4a SGML module, which more or less deprecates it. As the name
637 says, it handles only the DebianDoc DTD, which is more or less a
638 deprecated DTD.
639 xml2po.py
641 Used by the GIMP Documentation Team since 2004, works quite well
642 even if, as the name suggests, only with XML files and needs
643 specially configured makefiles.
644 Sphinx
646 The Sphinx Documentation Project also uses gettext extensively to
647 manage its translations. Unfortunately, it works only for a few
648 text formats, rest and markdown, although it is perhaps the only
649 tool that does this managing the whole translation process.
650 The main advantages of po4a over them are the ease of extra content
652 addition (which is even worse there) and the ability to achieve
653 gettextization.
654 SUMMARY of the advantages of the gettext based approach
656 • The translations are not stored along with the original, which makes
657 it possible to detect if translations become out of date.
658 • The translations are stored in separate files from each other, which
660 prevents translators of different languages from interfering, both
661 when submitting their patch and at the file encoding level.
662 • It is based internally on gettext (but po4a offers a very simple
664 interface so that you don't need to understand the internals to use
665 it). That way, we don't have to re-implement the wheel, and because
666 of their wide use, we can think that these tools are more or less bug
667 free.
668 • Nothing changed for the end-user (beside the fact translations will
670 hopefully be better maintained). The resulting documentation file
671 distributed is exactly the same.
672 • No need for translators to learn a new file syntax and their favorite
674 PO file editor (like Emacs' PO mode, Lokalize or Gtranslator) will
675 work just fine.
676 • gettext offers a simple way to get statistics about what is done,
678 what should be reviewed and updated, and what is still to do. Some
679 example can be found at those addresses:
680 - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
682 - http://www.debian.org/intl/l10n/
683 But everything isn't green, and this approach also has some
685 disadvantages we have to deal with.
686 • Addenda are… strange at the first glance.
688 • You can't adapt the translated text to your preferences, like
690 splitting a paragraph here, and joining two other ones there. But in
691 some sense, if there is an issue with the original, it should be
692 reported as a bug anyway.
693 • Even with an easy interface, it remains a new tool people have to
695 learn.
696 One of my dreams would be to integrate somehow po4a to Gtranslator or
698 Lokalize. When a documentation file is opened, the strings are
699 automatically extracted, and a translated file + po file can be
700 written to disk. If we manage to do an MS Word (TM) module (or at
701 least RTF) professional translators may even use it.
702
704 • The documentation of the all-in-one tool that you should use:
705 po4a(1).
706 • The documentation of the individual po4a scripts:
708 po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1),
709 po4a-normalize(1).
710 • The additional helping scripts: msguntypot(1), po4a-display-man(1),
712 po4a-display-pod(1).
713 • The parsers of each formats, in particular to see the options
715 accepted by each of them: Locale::Po4a::AsciiDoc(3pm)
716 Locale::Po4a::Dia(3pm), Locale::Po4a::Guide(3pm),
717 Locale::Po4a::Ini(3pm), Locale::Po4a::KernelHelp(3pm),
718 Locale::Po4a::Man(3pm), Locale::Po4a::RubyDoc(3pm),
719 Locale::Po4a::Texinfo(3pm), Locale::Po4a::Text(3pm),
720 Locale::Po4a::Xhtml(3pm), Locale::Po4a::Yaml(3pm),
721 Locale::Po4a::BibTeX(3pm), Locale::Po4a::Docbook(3pm),
722 Locale::Po4a::Halibut(3pm), Locale::Po4a::LaTeX(3pm),
723 Locale::Po4a::Pod(3pm), Locale::Po4a::Sgml(3pm),
724 Locale::Po4a::TeX(3pm), Locale::Po4a::Wml(3pm),
725 Locale::Po4a::Xml(3pm).
726 • The implementation of the core infrastructure:
728 Locale::Po4a::TransTractor(3pm) (particularly important to
729 understand the code organization), Locale::Po4a::Chooser(3pm),
730 Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). Please also check
731 the CONTRIBUTING.md file in the source tree.
732
734 Denis Barbier <barbier,linuxfr.org>
735 Martin Quinson (mquinson#debian.org)
736Po4a Tools 2023-01-23 PO4A(7)