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 format.
161 See Locale::Po4a:Guide for greater details.
163 Wml (probably mature parser)
165 The Web Markup Language, do not mixup WML with the WAP stuff used
166 on cell phones. This module relies on the Xhtml module, which
167 itself relies on the XmL module.
168 See Locale::Po4A::Wml for greater details.
170 Yaml (probably mature parser)
172 A strict superset of JSON, YAML is often used as systems or
173 configuration projects. YAML is at the core of Red Hat's Ansible.
174 See Locale::Po4A::Yaml for greater details.
176 RubyDoc (probably mature parser)
178 The Ruby Document (RD) format, originally the default documentation
179 format for Ruby and Ruby projects before converted to RDoc in 2002.
180 Though apparently the Japanese version of the Ruby Reference Manual
181 still use RD.
182 See Locale::Po4A::RubyDoc for greater details.
184 Halibut (probably experimental parser)
186 A documentation production system, with elements similar to TeX,
187 debiandoc-sgml, TeXinfo, and others, developed by Simon Tatham, the
188 developer of PuTTY.
189 See Locale::Po4a:Halibut for greater details.
191 Ini (probably experimental parser)
193 Configuration file format popularized by MS-DOS.
194 See Locale::Po4a::Ini for greater details.
196 texinfo (very highly experimental parser)
198 All of the GNU documentation is written in this format (it's even
199 one of the requirements to become an official GNU project). The
200 support for Locale::Po4a::Texinfo(3pm) in po4a is still at the
201 beginning. Please report bugs and feature requests.
202 Others supported formats
204 Po4a can also handle some more rare or specialized formats, such as
205 the documentation of compilation options for the 2.4+ Linux kernels
206 (Locale::Po4A::KernelHelp) or the diagrams produced by the dia tool
207 (Locale::Po4a:Dia). Adding a new format is often very easy and the
208 main task is to come up with a parser for your target format. See
209 Locale::Po4a::TransTractor(3pm) for more information about this.
210 Unsupported formats
212 Unfortunately, po4a still lacks support for several documentation
213 formats. Many of them would be easy to support in po4a. This
214 includes formats not just used for documentation, such as, package
215 descriptions (deb and rpm), package installation scripts questions,
216 package changelogs, and all the specialized file formats used by
217 programs such as game scenarios or wine resource files.
218
220 Historically, po4a was built around four scripts, each fulfilling a
221 specific task. po4a-gettextize(1) helps bootstrapping translations and
222 optionally converting existing translation projects to po4a.
223 po4a-updatepo(1) reflects the changes to the original documentation
224 into the corresponding po files. po4a-translate(1) builds translated
225 source file from the original file and the corresponding PO file. In
226 addition, po4a-normalize(1) is mostly useful to debug the po4a parsers,
227 as it produces an untranslated document from the original one. It makes
228 it easier to spot the glitches introduced by the parsing process.
229 Most projects only require the features of po4a-updatepo(1) and
231 po4a-translate(1), but these scripts proved to be cumbersome and error
232 prone to use. If the documentation to translate is split over several
233 source files, it is difficult to keep the PO files up to date and build
234 the documentation files correctly. As an answer, a all-in-one tool was
235 provided: po4a(1). This tool takes a configuration file describing the
236 structure of the translation project: the location of the PO files, the
237 list of files to translate, and the options to use, and it fully
238 automatizes the process. When you invoke po4a(1), it both updates the
239 PO files and regenerate the translation files that need to. If
240 everything is already up to date, po4a(1) does not change any file.
241 The rest of this section gives an overview of how use the scripts'
243 interface of po4a. Most users will probably prefer to use the all-in-
244 one tool, that is described in the documentation of po4a(1).
245 Graphical overview of the po4a scripts
247 The following schema gives an overview of how each po4a script can be
248 used. Here, master.doc is an example name for the documentation to be
249 translated; XX.doc is the same document translated in the language XX
250 while doc.XX.po is the translation catalog for that document in the XX
251 language. Documentation authors will mostly be concerned with
252 master.doc (which can be a manpage, an XML document, an asciidoc file
253 or similar); the translators will be mostly concerned with the PO file,
254 while the end users will only see the XX.doc file.
255 master.doc
257 |
258 V
259 +<-----<----+<-----<-----<--------+------->-------->-------+
260 : | | :
261 {translation} | { update of master.doc } :
262 : | | :
263 XX.doc | V V
264 (optional) | master.doc ->-------->------>+
265 : | (new) |
266 V V | |
267 [po4a-gettextize] doc.XX.po -->+ | |
268 | (old) | | |
269 | ^ V V |
270 | | [po4a-updatepo] |
271 V | | V
272 translation.pot ^ V |
273 | | doc.XX.po |
274 | | (fuzzy) |
275 { translation } | | |
276 | ^ V V
277 | | {manual editing} |
278 | | | |
279 V | V V
280 doc.XX.po --->---->+<---<-- doc.XX.po addendum master.doc
281 (initial) (up-to-date) (optional) (up-to-date)
282 : | | |
283 : V | |
284 +----->----->----->------> + | |
285 | | |
286 V V V
287 +------>-----+------<------+
288 |
289 V
290 [po4a-translate]
291 |
292 V
293 XX.doc
294 (up-to-date)
295 This schema is complicated, but in practice only the right part
297 (involving po4a-updatepo(1) and po4a-translate(1)) is used once the
298 project is setup and configured.
299 The left part depicts how po4a-gettextize(1) can be used to convert an
301 existing translation project to the po4a infrastructure. This script
302 takes an original document and its translated counterpart, and tries to
303 build the corresponding PO file. Such manual conversion is rather
304 cumbersome (see the po4a-gettextize(1) documentation for more details),
305 but it is only needed once to convert your existing translations. If
306 you don't have any translation to convert, you can forget about this
307 and focus on the right part of the schema.
308 On the top right part, the action of the original author is depicted,
310 updating the documentation. The middle right part depicts the automatic
311 actions of po4a-updatepo(1). The new material is extracted and compared
312 against the exiting translation. The previous translation is used for
313 the parts that didn't change, while partially modified parts are
314 connected to the previous translation with a "fuzzy" marker indicating
315 that the translation must be updated. New or heavily modified material
316 is left untranslated.
317 Then, the manual editing reported depicts the action of the
319 translators, that modify the PO files to provide translations to every
320 original string and paragraph. This can be done using either a specific
321 editor such as the GNOME Translation Editor, KDE's Lokalize or poedit,
322 or using an online localization platform such as weblate or pootle. The
323 translation result is a set of PO files, one per language. Please refer
324 to the gettext documentation for more details.
325 The bottom part of the figure shows how po4a-translate(1) creates a
327 translated source document from the master.doc original document and
328 the doc.XX.po translation catalog that was updated by the translators.
329 The structure of the document is reused, while the original content is
330 replaced by its translated counterpart. Optionally, an addendum can be
331 used to add some extra text to the translation. This is often used to
332 add the name of the translator to the final document. See below for
333 details.
334 As noted before, the po4a(1) program combines the effects of the
336 separated scripts, updating the PO files and the translated document in
337 one invocation. The underlying logic remains the same.
338 Starting a new translation
340 If you use po4a(1), there is no specific step to start a translation.
341 You just have to list the languages in the configuration file, and the
342 missing PO files are automatically created. Naturally, the translator
343 then have to provide translations for every content used in your
344 documents. po4a(1) also creates a POT file, that is a PO template file.
345 Potential translators can translate your project into a new language by
346 renaming this file and providing the translations in their language.
347 If you prefer to use the individual scripts separately, you should use
349 po4a-gettextize(1) as follows to create the POT file. This file can
350 then be copied into XX.po to initiate a new translation.
351 $ po4a-gettextize --format <format> --master <master.doc> --po <translation.pot>
353 The master document is used in input, while the POT file is the output
355 of this process.
356 Integrating changes to the original document
358 The script to use for that is po4a-updatepo(1) (please refer to its
359 documentation for details):
360 $ po4a-updatepo --format <format> --master <new_master.doc> --po <old_doc.XX.po>
362 The master document is used in input, while the PO file is updated: it
364 is used both in input and output.
365 Generating a translated document
367 Once you're done with the translation, you want to get the translated
368 documentation and distribute it to users along with the original one.
369 For that, use the po4a-translate(1) program as follows:
370 $ po4a-translate --format <format> --master <master.doc> --po <doc.XX.po> --localized <XX.doc>
372 Both the master and PO files are used in input, while the localized
374 file is the output of this process.
375 Using addenda to add extra text to translations
377 Adding new text to the translation is probably the only thing that is
378 easier in the long run when you translate files manually :). This
379 happens when you want to add an extra section to the translated
380 document, not corresponding to any content in the original document.
381 The classical use case is to give credits to the translation team, and
382 to indicate how to report translation-specific issues.
383 With po4a, you have to specify addendum files, that can be conceptually
385 viewed as patches applied to the localized document after processing.
386 Each addendum must be provided as a separate file, which format is
387 however very different from the classical patches. The first line is a
388 header line, defining the insertion point of the addendum (with an
389 unfortunately cryptic syntax -- see below) while the rest of the file
390 is added verbatim at the determined position.
391 The header line must begin with the string PO4A-HEADER:, followed by a
393 semi-colon separated list of key=value fields.
394 For example, the following header declares an addendum that must be
396 placed at the very end of the translation.
397 PO4A-HEADER: mode=eof
399 Things are more complex when you want to add your extra content in the
401 middle of the document. The following header declares an addendum that
402 must be placed after the XML section containing the string "About this
403 document" in translation.
404 PO4A-HEADER: position=About this document; mode=after; endboundary=</section>
406 In practice, when trying to apply an addendum, po4a searches for the
408 first line matching the "position" argument (this can be a regexp). Do
409 not forget that po4a considers the translated document here. This
410 documentation is in English, but your line should probably read as
411 follows if you intend your addendum to apply to the French translation
412 of the document.
413 PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>
415 Once the "position" is found in the target document, po4a searches for
417 the next line after the "position" that matches the provided
418 "endboundary". The addendum is added right after that line (because we
419 provided an endboundary, i.e. a boundary ending the current section).
420 The exact same effect could be obtained with the following header, that
422 is equivalent:
423 PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>
425 Here, po4a searches for the first line matching "<section"> after the
427 line matching "About this document" in the translation, and add the
428 addendum before that line since we provided a beginboundary, i.e. a
429 boundary marking the beginning of the next section. So this header line
430 requires to place the addendum after the section containing "About this
431 document", and instruct po4a that a section starts with a line
432 containing the "<section"> tag. This is equivalent to the previous
433 example because what you really want is to add this addendum either
434 after "/section"> or before "<section">.
435 You can also set the insertion mode to the value "before", with a
437 similar semantic: combining "mode=before" with an "endboundary" will
438 put the addendum just after the matched boundary, that the last
439 potential boundary line before the "position". Combining "mode=before"
440 with an "beginboundary" will put the addendum just before the matched
441 boundary, that the last potential boundary line before the "position".
442 Mode | Boundary kind | Used boundary | Insertion point compared to the boundary
444 ========|===============|========================|=========================================
445 'before'| 'endboundary' | last before 'position' | Right after the selected boundary
446 'before'|'beginboundary'| last before 'position' | Right before the selected boundary
447 'after' | 'endboundary' | first after 'position' | Right after the selected boundary
448 'after' |'beginboundary'| first after 'position' | Right before the selected boundary
449 'eof' | (none) | n/a | End of file
450 Hint and tricks about addenda
452 • Remember that these are regexp. For example, if you want to match
454 the end of a nroff section ending with the line ".fi", do not use
455 ".fi" as endboundary, because it will match with "the[ fi]le",
456 which is obviously not what you expect. The correct endboundary in
457 that case is: "^\.fi$".
458 • White spaces ARE important in the content of the "position" and
460 boundaries. So the two following lines are different. The second
461 one will only be found if there is enough trailing spaces in the
462 translated document.
463 PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>
465 PO4A-HEADER: position=About this document ; mode=after; beginboundary=<section>
466 • Although this context search may be considered to operate roughly
468 on each line of the translated document, it actually operates on
469 the internal data string of the translated document. This internal
470 data string may be a text spanning a paragraph containing multiple
471 lines or may be a XML tag itself alone. The exact insertion point
472 of the addendum must be before or after the internal data string
473 and can not be within the internal data string.
474 • Pass the -vv argument to po4a to understand how the addenda are
476 added to the translation. It may also help to run po4a in debug
477 mode to see the actual internal data string when your addendum does
478 not apply.
479 Addenda examples
481 • If you want to add something after the following nroff section:
483 .SH "AUTHORS"
485 You should select a two step approach by setting mode=after. Then
487 you should narrow down search to the line after AUTHORS with the
488 position argument regex. Then, you should match the beginning of
489 the next section (i.e., ^\.SH) with the beginboundary argument
490 regex. That is to say:
491 PO4A-HEADER:mode=after;position=AUTHORS;beginboundary=\.SH
493 • If you want to add something right after a given line (e.g. after
495 the line "Copyright Big Dude"), use a position matching this line,
496 mode=after and give a beginboundary matching any line.
497 PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^
499 • If you want to add something at the end of the document, give a
501 position matching any line of your document (but only one line.
502 Po4a won't proceed if it's not unique), and give an endboundary
503 matching nothing. Don't use simple strings here like "EOF", but
504 prefer those which have less chance to be in your document.
505 PO4A-HEADER:mode=after;position=About this document;beginboundary=FakePo4aBoundary
507 More detailed example
509 Original document (POD formatted):
511 |=head1 NAME
513 |
514 |dummy - a dummy program
515 |
516 |=head1 AUTHOR
517 |
518 |me
519 Then, the following addendum will ensure that a section (in French)
521 about the translator is added at the end of the file (in French,
522 "TRADUCTEUR" means "TRANSLATOR", and "moi" means "me").
523 |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
525 |
526 |=head1 TRADUCTEUR
527 |
528 |moi
529 |
530 To put your addendum before the AUTHOR, use the following header:
532 PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1
534 This works because the next line matching the beginboundary /^=head1/
536 after the section "NAME" (translated to "NOM" in French), is the one
537 declaring the authors. So, the addendum will be put between both
538 sections. Note that if another section is added between NAME and AUTHOR
539 sections later, po4a will wrongfully put the addenda before the new
540 section.
541 To avoid this you may accomplish the same using mode=before:
543 PO4A-HEADER:mode=before;position=^=head1 AUTEUR
545
547 This chapter gives you a brief overview of the po4a internals, so that
548 you may feel more confident to help us maintaining and improving it. It
549 may also help you understanding why it does not do what you expected,
550 and how to solve your problems.
551 The po4a architecture is object oriented. The
553 Locale::Po4a::TransTractor(3pm) class is the common ancestor to all
554 po4a parsers. This strange name comes from the fact that it is at the
555 same time in charge of translating document and extracting strings.
556 More formally, it takes a document to translate plus a PO file
558 containing the translations to use as input while producing two
559 separate outputs: Another PO file (resulting of the extraction of
560 translatable strings from the input document), and a translated
561 document (with the same structure than the input one, but with all
562 translatable strings replaced with content of the input PO). Here is a
563 graphical representation of this:
564 Input document --\ /---> Output document
566 \ TransTractor:: / (translated)
567 +-->-- parse() --------+
568 / \
569 Input PO --------/ \---> Output PO
570 (extracted)
571 This little bone is the core of all the po4a architecture. If you omit
573 the input PO and the output document, you get po4a-gettextize. If you
574 provide both input and disregard the output PO, you get po4a-translate.
575 The po4a calls TransTractor twice and calls msgmerge -U between these
576 TransTractor invocations to provide one-stop solution with a single
577 configuration file. Please see Locale::Po4a::TransTractor(3pm) for
578 more details.
579
581 Here is a very partial list of projects that use po4a in production for
582 their documentation. If you want to add your project to the list, just
583 drop us an email (or a Merge Request).
584 • adduser (man): users and groups management tool.
586 • apt (man, docbook): Debian package manager.
588 • aptitude (docbook, svg): terminal-based package manager for Debian
590 • F-Droid website <https://gitlab.com/fdroid/fdroid-website>
592 (markdown): installable catalogue of FOSS (Free and Open Source
593 Software) applications for the Android platform.
594 • git <https://github.com/jnavila/git-manpages-l10n> (asciidoc):
596 distributed version-control system for tracking changes in source
597 code.
598 • Linux manpages <https://salsa.debian.org/manpages-l10n-
600 team/manpages-l10n> (man)
601 This project provides an infrastructure for translating many
603 manpages to different languages, ready for integration into several
604 major distributions (Arch Linux, Debian and derivatives, Fedora).
605 • Stellarium <https://github.com/Stellarium/stellarium> (HTML): a
607 free open source planetarium for your computer. po4a is used to
608 translate the sky culture descriptions.
609 • Other item to sort out: https://gitlab.com/fdroid/fdroid-website/
611 https://github.com/fsfe/reuse-docs/pull/61
612
614 How do you pronounce po4a?
615 I personally vocalize it as pouah
616 <https://en.wiktionary.org/wiki/pouah>, which is a French onomatopoetic
617 that we use in place of yuck :) I may have a strange sense of humor :)
618 What about the other translation tools for documentation using gettext?
620 As far as I know, there are only two of them:
621 poxml
623 This is the tool developed by KDE people to handle DocBook XML.
624 AFAIK, it was the first program to extract strings to translate
625 from documentation to PO files, and inject them back after
626 translation.
627 It can only handle XML, and only a particular DTD. I'm quite
629 unhappy with the handling of lists, which end in one big msgid.
630 When the list become big, the chunk becomes harder to swallow.
631 po-debiandoc
633 This program done by Denis Barbier is a sort of precursor of the
634 po4a SGML module, which more or less deprecates it. As the name
635 says, it handles only the DebianDoc DTD, which is more or less a
636 deprecated DTD.
637 The main advantages of po4a over them are the ease of extra content
639 addition (which is even worse there) and the ability to achieve
640 gettextization.
641 SUMMARY of the advantages of the gettext based approach
643 • The translations are not stored along with the original, which makes
644 it possible to detect if translations become out of date.
645 • The translations are stored in separate files from each other, which
647 prevents translators of different languages from interfering, both
648 when submitting their patch and at the file encoding level.
649 • It is based internally on gettext (but po4a offers a very simple
651 interface so that you don't need to understand the internals to use
652 it). That way, we don't have to re-implement the wheel, and because
653 of their wide use, we can think that these tools are more or less bug
654 free.
655 • Nothing changed for the end-user (beside the fact translations will
657 hopefully be better maintained). The resulting documentation file
658 distributed is exactly the same.
659 • No need for translators to learn a new file syntax and their favorite
661 PO file editor (like Emacs' PO mode, Lokalize or Gtranslator) will
662 work just fine.
663 • gettext offers a simple way to get statistics about what is done,
665 what should be reviewed and updated, and what is still to do. Some
666 example can be found at those addresses:
667 - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
669 - http://www.debian.org/intl/l10n/
670 But everything isn't green, and this approach also has some
672 disadvantages we have to deal with.
673 • Addenda are… strange at the first glance.
675 • You can't adapt the translated text to your preferences, like
677 splitting a paragraph here, and joining two other ones there. But in
678 some sense, if there is an issue with the original, it should be
679 reported as a bug anyway.
680 • Even with an easy interface, it remains a new tool people have to
682 learn.
683 One of my dreams would be to integrate somehow po4a to Gtranslator or
685 Lokalize. When a documentation file is opened, the strings are
686 automatically extracted, and a translated file + po file can be
687 written to disk. If we manage to do an MS Word (TM) module (or at
688 least RTF) professional translators may even use it.
689
691 • The documentation of the all-in-one tool that you should use:
692 po4a(1).
693 • The documentation of the individual po4a scripts:
695 po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1),
696 po4a-normalize(1).
697 • The additional helping scripts: msguntypot(1), po4a-display-man(1),
699 po4a-display-pod(1).
700 • The parsers of each formats, in particular to see the options
702 accepted by each of them: Locale::Po4a::AsciiDoc(3pm)
703 Locale::Po4a::Dia(3pm), Locale::Po4a::Guide(3pm),
704 Locale::Po4a::Ini(3pm), Locale::Po4a::KernelHelp(3pm),
705 Locale::Po4a::Man(3pm), Locale::Po4a::RubyDoc(3pm),
706 Locale::Po4a::Texinfo(3pm), Locale::Po4a::Text(3pm),
707 Locale::Po4a::Xhtml(3pm), Locale::Po4a::Yaml(3pm),
708 Locale::Po4a::BibTeX(3pm), Locale::Po4a::Docbook(3pm),
709 Locale::Po4a::Halibut(3pm), Locale::Po4a::LaTeX(3pm),
710 Locale::Po4a::Pod(3pm), Locale::Po4a::Sgml(3pm),
711 Locale::Po4a::TeX(3pm), Locale::Po4a::Wml(3pm),
712 Locale::Po4a::Xml(3pm).
713 • The implementation of the core infrastructure:
715 Locale::Po4a::TransTractor(3pm) (particularly important to
716 understand the code organization), Locale::Po4a::Chooser(3pm),
717 Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). Please also check
718 the CONTRIBUTING.md file in the source tree.
719
721 Denis Barbier <barbier,linuxfr.org>
722 Martin Quinson (mquinson#debian.org)
723Po4a Tools 2021-11-01 PO4A(7)