1PO4A.7(1)             User Contributed Perl Documentation            PO4A.7(1)
2
3
4

NAME

6       po4a - framework to translate documentation and other materials
7

Introduction

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
14       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

Why po4a?

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
25       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
30       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
38       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
46       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
55       The goal of the po4a project is to ease the work of documentation
56       translators.  In particular, it makes documentation translations
57       maintainable.
58
59       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
70       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
76       Please also see the FAQ below in this document for a more complete list
77       of the advantages and disadvantages of this approach.
78
79   Supported formats
80       Currently, this approach has been successfully implemented to several
81       kinds of text formatting formats:
82
83       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
88           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
91       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
96           See Locale::Po4a::AsciiDoc for details.
97
98       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
106           See Locale::Po4a::Pod for details.
107
108       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
116           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
122       TeX / LaTeX (mature parser)
123           The LaTeX format is a major documentation format used in the Free
124           Software world and for publications.
125
126           The Locale::Po4a::LaTeX(3pm) module was tested with the Python
127           documentation, a book and some presentations.
128
129       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
134           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
138       xml and XHMTL (probably mature parser)
139           The XML format is a base format for many documentation formats.
140
141           Currently, the DocBook DTD (see Locale::Po4a::Docbook(3pm) for
142           details) and XHTML are supported by po4a.
143
144       BibTex (probably mature parser)
145           The BibTex format is used alongside LaTex for formatting lists of
146           references (bibliographies).
147
148           See Locale::Po4a::BibTex for details.
149
150       Docbook (probably mature parser)
151           A XML-based markup language that uses semantic tags to describe
152           documents.
153
154           See Locale::Po4a:Docbook for greater details.
155
156       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
163           See Locale::Po4a:Guide for greater details.
164
165       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
170           See Locale::Po4a::Wml for greater details.
171
172       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
176           See Locale::Po4a::Yaml for greater details.
177
178       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
184           See Locale::Po4a::RubyDoc for greater details.
185
186       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
191           See Locale::Po4a:Halibut for greater details.
192
193       Ini (probably experimental parser)
194           Configuration file format popularized by MS-DOS.
195
196           See Locale::Po4a::Ini for greater details.
197
198       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
204       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
212       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

Using po4a

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
231       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
243       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
247   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
257                                          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
297       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
301       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
310       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
319       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
327       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
336       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
340   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
349       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
353         $ po4a-gettextize --format <format> --master <master.doc> --po <translation.pot>
354
355       The master document is used in input, while the POT file is the output
356       of this process.
357
358   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
362         $ po4a-updatepo --format <format> --master <new_master.doc> --po <old_doc.XX.po>
363
364       The master document is used in input, while the PO file is updated: it
365       is used both in input and output.
366
367   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
372         $ po4a-translate --format <format> --master <master.doc> --po <doc.XX.po> --localized <XX.doc>
373
374       Both the master and PO files are used in input, while the localized
375       file is the output of this process.
376
377   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
385       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
393       The header line must begin with the string PO4A-HEADER:, followed by a
394       semi-colon separated list of key=value fields.
395
396       For example, the following header declares an addendum that must be
397       placed at the very end of the translation.
398
399        PO4A-HEADER: mode=eof
400
401       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
406        PO4A-HEADER: position=About this document; mode=after; endboundary=</section>
407
408       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
415        PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>
416
417       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
422       The exact same effect could be obtained with the following header, that
423       is equivalent:
424
425        PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>
426
427       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
437       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
444         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
452       Hint and tricks about addenda
453
454       •   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
460       •   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
465            PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>
466            PO4A-HEADER: position=About this document ; mode=after; beginboundary=<section>
467
468       •   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
476       •   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
481       Addenda examples
482
483       •   If you want to add something after the following nroff section:
484
485             .SH "AUTHORS"
486
487           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
493            PO4A-HEADER:mode=after;position=AUTHORS;beginboundary=\.SH
494
495       •   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
499            PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^
500
501       •   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
507            PO4A-HEADER:mode=after;position=About this document;beginboundary=FakePo4aBoundary
508
509       More detailed example
510
511       Original document (POD formatted):
512
513        |=head1 NAME
514        |
515        |dummy - a dummy program
516        |
517        |=head1 AUTHOR
518        |
519        |me
520
521       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
525        |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
526        |
527        |=head1 TRADUCTEUR
528        |
529        |moi
530        |
531
532       To put your addendum before the AUTHOR, use the following header:
533
534        PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1
535
536       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
543       To avoid this you may accomplish the same using mode=before:
544
545        PO4A-HEADER:mode=before;position=^=head1 AUTEUR
546

How does it work?

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
553       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
558       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
566          Input document --\                             /---> Output document
567                            \      TransTractor::       /       (translated)
568                             +-->--   parse()  --------+
569                            /                           \
570          Input PO --------/                             \---> Output PO
571                                                                (extracted)
572
573       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

Open-source projects using po4a

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
586       •   adduser (man): users and groups management tool.
587
588       •   apt (man, docbook): Debian package manager.
589
590       •   aptitude (docbook, svg): terminal-based package manager for Debian
591
592       •   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
596       •   git <https://github.com/jnavila/git-manpages-l10n> (asciidoc):
597           distributed version-control system for tracking changes in source
598           code.
599
600       •   Linux manpages <https://salsa.debian.org/manpages-l10n-
601           team/manpages-l10n> (man)
602
603           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
607       •   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
611       •   Other item to sort out: <https://gitlab.com/fdroid/fdroid-website/>
612           <https://github.com/fsfe/reuse-docs/pull/61>
613

FAQ

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
620   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
624       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
630           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
634       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
640       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
645       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
651       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
655   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
659       • 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
663       • 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
669       • 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
673       • 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
677       • 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
681          - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
682          - http://www.debian.org/intl/l10n/
683
684       But everything isn't green, and this approach also has some
685       disadvantages we have to deal with.
686
687       • Addenda are… strange at the first glance.
688
689       • 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
694       • Even with an easy interface, it remains a new tool people have to
695         learn.
696
697         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

SEE ALSO

704       •   The documentation of the all-in-one tool that you should use:
705           po4a(1).
706
707       •   The documentation of the individual po4a scripts:
708           po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1),
709           po4a-normalize(1).
710
711       •   The additional helping scripts: msguntypot(1), po4a-display-man(1),
712           po4a-display-pod(1).
713
714       •   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
727       •   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

AUTHORS

734        Denis Barbier <barbier,linuxfr.org>
735        Martin Quinson (mquinson#debian.org)
736
737
738
739perl v5.36.0                      2023-01-23                         PO4A.7(1)
Impressum