Provided by: po4a_0.69-1_all bug

NAME

       po4a - framework to translate documentation and other materials

Introduction

       po4a (PO for anything) eases the maintenance of documentation translation using the classical gettext
       tools. The main feature of po4a is that it decouples the translation of content from its document
       structure.

       This document serves as an introduction to the po4a project with a focus on potential users considering
       whether to use this tool and on the curious wanting to understand why things are the way they are.

Why po4a?

       The philosophy of Free Software is to make the technology truly available to everyone. But licensing is
       not the only consideration: untranslated free software is useless for non-English speakers. Therefore, we
       still have some work to do to make software available to everybody.

       This situation is well understood by most projects and everybody is now convinced of the necessity to
       translate everything. Yet, the actual translations represent a huge effort of many individuals, crippled
       by small technical difficulties.

       Thankfully, Open Source software is actually very well translated using the gettext tool suite. These
       tools are used to extract the strings to translate from a program and present the strings to translate in
       a standardized format (called PO files, or translation catalogs). A whole ecosystem of tools has emerged
       to help the translators actually translate these PO files. The result is then used by gettext at run time
       to display translated messages to the end users.

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

       Outdated translations are often worse than no translation at all. End-users can be tricked by
       documentation describing an old behavior of the program.  Furthermore, they cannot interact directly with
       the maintainers since they don't speak English. Additionally, the maintainer cannot fix the problem as
       they don't know every language in which their documentation is translated.  These difficulties, often
       caused by poor tooling, can undermine the motivation of volunteer translators, further aggravating the
       problem.

       The goal of the po4a project is to ease the work of documentation translators.  In particular, it makes
       documentation translations maintainable.

       The idea is to reuse and adapt the gettext approach to this field. As with gettext, texts are extracted
       from their original locations and presented to translators as PO translation catalogs. The translators
       can leverage the classical gettext tools to monitor the work to do, collaborate and organize as teams.
       po4a then injects the translations directly into the documentation structure to produce translated source
       files that can be processed and distributed just like the English files. Any paragraph that is not
       translated is left in English in the resulting document, ensuring that the end users never see an
       outdated translation in the documentation.

       This automates most of the grunt work of the translation maintenance.  Discovering the paragraphs needing
       an update becomes very easy, and the process is completely automated when elements are reordered without
       further modification. Specific verification can also be used to reduce the chance of formatting errors
       that would result in a broken document.

       Please also see the FAQ below in this document for a more complete list of the advantages and
       disadvantages of this approach.

   Supported formats
       Currently, this approach has been successfully implemented to several kinds of text formatting formats:

       man (mature parser)
           The  good  old manual pages' format, used by so many programs out there. po4a support is very welcome
           here since this format is somewhat difficult to use and not really friendly to newbies.

           The Locale::Po4a::Man(3pm) module also supports the mdoc format, used by the BSD man pages (they  are
           also quite common on Linux).

       AsciiDoc (mature parser)
           This format is a lightweight markup format intended to ease the authoring of documentation. It is for
           example used to document the git system. Those manpages are translated using po4a.

           See Locale::Po4a::AsciiDoc for details.

       pod (mature parser)
           This  is  the Perl Online Documentation format. The language and extensions themselves are documented
           using this format in addition to most existing Perl scripts. It makes easy to keep the  documentation
           close  to the actual code by embedding them both in the same file. It makes programmer's life easier,
           but unfortunately, not the translator's, until you use po4a.

           See Locale::Po4a::Pod for details.

       sgml (mature parser)
           Even if superseded by XML nowadays, this format is still used for documents which are more than a few
           screens long. It can even be used  for  complete  books.   Documents  of  this  length  can  be  very
           challenging  to  update.  diff  often  reveals  useless  when the original text was re-indented after
           update.  Fortunately, po4a can help you after that process.

           Currently, only DebianDoc and DocBook DTD are supported, but adding support for a new one  is  really
           easy.  It  is even possible to use po4a on an unknown SGML DTD without changing the code by providing
           the needed information on the command line. See Locale::Po4a::Sgml(3pm) for details.

       TeX / LaTeX (mature parser)
           The LaTeX format  is  a  major  documentation  format  used  in  the  Free  Software  world  and  for
           publications.

           The  Locale::Po4a::LaTeX(3pm)  module  was  tested  with  the  Python  documentation, a book and some
           presentations.

       text (mature parser)
           The Text format is the base format for many formats that  include  long  blocks  of  text,  including
           Markdown, fortunes, YAML front matter section, debian/changelog, and debian/control.

           This  supports  the  common  format  used in Static Site Generators, READMEs, and other documentation
           systems. See Locale::Po4a::Text(3pm) for details.

       xml and XHMTL (probably mature parser)
           The XML format is a base format for many documentation formats.

           Currently, the DocBook DTD (see Locale::Po4a::Docbook(3pm) for details) and XHTML  are  supported  by
           po4a.

       BibTex (probably mature parser)
           The BibTex format is used alongside LaTex for formatting lists of references (bibliographies).

           See Locale::Po4a::BibTex for details.

       Docbook (probably mature parser)
           A XML-based markup language that uses semantic tags to describe documents.

           See Locale::Po4a:Docbook for greater details.

       Guide XML (probably mature parser)
           A  XML  documentation  format.  This  module  was  developed specifically to help with supporting and
           maintaining translations of Gentoo Linux documentation up until at least March  2016  (Based  on  the
           Wayback Machine). Gentoo have since moved to the DevBook XML format.

           See Locale::Po4a:Guide for greater details.

       Wml (probably mature parser)
           The Web Markup Language, do not mixup WML with the WAP stuff used on cell phones.  This module relies
           on the Xhtml module, which itself relies on the XmL module.

           See Locale::Po4a::Wml for greater details.

       Yaml (probably mature parser)
           A  strict  superset of JSON. YAML is often used as systems or configuration projects.  YAML is at the
           core of Red Hat's Ansible.

           See Locale::Po4a::Yaml for greater details.

       RubyDoc (probably mature parser)
           The Ruby Document (RD) format, originally the default documentation format for Ruby and Ruby projects
           before converted to RDoc in 2002. Though apparently the Japanese version of the Ruby Reference Manual
           still use RD.

           See Locale::Po4a::RubyDoc for greater details.

       Halibut (probably experimental parser)
           A documentation production system, with elements similar to TeX, debiandoc-sgml, TeXinfo, and others,
           developed by Simon Tatham, the developer of PuTTY.

           See Locale::Po4a:Halibut for greater details.

       Ini (probably experimental parser)
           Configuration file format popularized by MS-DOS.

           See Locale::Po4a::Ini for greater details.

       texinfo (very highly experimental parser)
           All of the GNU documentation is written in this format (it's even one of the requirements  to  become
           an  official  GNU  project).  The  support  for  Locale::Po4a::Texinfo(3pm)  in  po4a is still at the
           beginning.  Please report bugs and feature requests.

       Others supported formats
           Po4a can also handle some more rare or specialized formats, such as the documentation of  compilation
           options  for  the  2.4+  Linux kernels (Locale::Po4a::KernelHelp) or the diagrams produced by the dia
           tool (Locale::Po4a:Dia). Adding a new format is often very easy and the main task is to come up  with
           a parser for your target format. See Locale::Po4a::TransTractor(3pm) for more information about this.

       Unsupported formats
           Unfortunately, po4a still lacks support for several documentation formats. Many of them would be easy
           to  support  in  po4a.  This  includes  formats  not  just  used  for documentation, such as, package
           descriptions (deb and rpm), package installation scripts questions, package changelogs, and  all  the
           specialized file formats used by programs such as game scenarios or wine resource files.

Using po4a

       Historically,  po4a  was  built  around four scripts, each fulfilling a specific task. po4a-gettextize(1)
       helps bootstrapping translations  and  optionally  converting  existing  translation  projects  to  po4a.
       po4a-updatepo(1)  reflects  the  changes  to  the original documentation into the corresponding po files.
       po4a-translate(1) builds translated source file from the original file and the corresponding PO file.  In
       addition,  po4a-normalize(1)  is  mostly useful to debug the po4a parsers, as it produces an untranslated
       document from the original one. It makes it easier  to  spot  the  glitches  introduced  by  the  parsing
       process.

       Most  projects  only  require  the  features of po4a-updatepo(1) and po4a-translate(1), but these scripts
       proved to be cumbersome and error prone to use. If the documentation to translate is split  over  several
       source  files,  it  is  difficult  to  keep  the  PO  files  up to date and build the documentation files
       correctly. As an answer, a all-in-one tool was provided: po4a(1). This tool takes  a  configuration  file
       describing  the  structure of the translation project: the location of the PO files, the list of files to
       translate, and the options to use, and it fully automates the process. When you invoke po4a(1),  it  both
       updates  the  PO  files and regenerate the translation files that need to. If everything is already up to
       date, po4a(1) does not change any file.

       The rest of this section gives an overview of how use the scripts' interface of  po4a.  Most  users  will
       probably prefer to use the all-in-one tool, that is described in the documentation of po4a(1).

   Graphical overview of the po4a scripts
       The  following  schema  gives  an  overview  of how each po4a script can be used.  Here, master.doc is an
       example name for the documentation to be translated; XX.doc  is  the  same  document  translated  in  the
       language  XX  while  doc.XX.po  is  the  translation  catalog  for  that  document  in  the  XX language.
       Documentation authors will mostly be concerned with master.doc (which can be a manpage, an XML  document,
       an  asciidoc  file  or similar); the translators will be mostly concerned with the PO file, while the end
       users will only see the XX.doc file.

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

       This schema is complicated,  but  in  practice  only  the  right  part  (involving  po4a-updatepo(1)  and
       po4a-translate(1)) is used once the project is setup and configured.

       The  left  part  depicts how po4a-gettextize(1) can be used to convert an existing translation project to
       the po4a infrastructure. This script takes an original document and its translated counterpart, and tries
       to  build  the  corresponding  PO  file.  Such  manual  conversion  is   rather   cumbersome   (see   the
       po4a-gettextize(1)  documentation  for more details), but it is only needed once to convert your existing
       translations. If you don't have any translation to convert, you can forget about this and  focus  on  the
       right part of the schema.

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

       Then,  the  manual  editing  reported  depicts the action of the translators, that modify the PO files to
       provide translations to every original string and paragraph. This can be done  using  either  a  specific
       editor  such  as  the GNOME Translation Editor, KDE's Lokalize or poedit, or using an online localization
       platform such as weblate or pootle. The translation result is a set of PO files, one per language. Please
       refer to the gettext documentation for more details.

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

       As noted before, the po4a(1) program combines the effects of the separated scripts, updating the PO files
       and the translated document in one invocation.  The underlying logic remains the same.

   Starting a new translation
       If you use po4a(1), there is no specific step to start a translation. You just have to list the languages
       in  the configuration file, and the missing PO files are automatically created. Naturally, the translator
       then have to provide translations for every content used in your documents. po4a(1) also  creates  a  POT
       file, that is a PO template file. Potential translators can translate your project into a new language by
       renaming this file and providing the translations in their language.

       If  you  prefer to use the individual scripts separately, you should use po4a-gettextize(1) as follows to
       create the POT file. This file can then be copied into XX.po to initiate a new translation.

         $ po4a-gettextize --format <format> --master <master.doc> --po <translation.pot>

       The master document is used in input, while the POT file is the output of this process.

   Integrating changes to the original document
       The script to use for that is po4a-updatepo(1) (please refer to its documentation for details):

         $ po4a-updatepo --format <format> --master <new_master.doc> --po <old_doc.XX.po>

       The master document is used in input, while the PO file is updated: it is used both in input and output.

   Generating a translated document
       Once you're done with the translation, you want to get the translated documentation and distribute it  to
       users along with the original one.  For that, use the po4a-translate(1) program as follows:

         $ po4a-translate --format <format> --master <master.doc> --po <doc.XX.po> --localized <XX.doc>

       Both the master and PO files are used in input, while the localized file is the output of this process.

   Using addenda to add extra text to translations
       Adding  new  text  to  the translation is probably the only thing that is easier in the long run when you
       translate files manually :). This happens when you want  to  add  an  extra  section  to  the  translated
       document,  not  corresponding  to any content in the original document. The classical use case is to give
       credits to the translation team, and to indicate how to report translation-specific issues.

       With po4a, you have to specify addendum files, that can be conceptually viewed as patches applied to  the
       localized  document  after processing. Each addendum must be provided as a separate file, which format is
       however very different from the classical patches.  The  first  line  is  a  header  line,  defining  the
       insertion point of the addendum (with an unfortunately cryptic syntax -- see below) while the rest of the
       file is added verbatim at the determined position.

       The  header  line  must  begin  with  the string PO4A-HEADER:, followed by a semi-colon separated list of
       key=value fields.

       For example, the following header declares an addendum that must  be  placed  at  the  very  end  of  the
       translation.

        PO4A-HEADER: mode=eof

       Things  are  more  complex  when  you  want  to add your extra content in the middle of the document. The
       following header declares an addendum that must be placed after the XML  section  containing  the  string
       "About this document" in translation.

        PO4A-HEADER: position=About this document; mode=after; endboundary=</section>

       In  practice,  when trying to apply an addendum, po4a searches for the first line matching the "position"
       argument (this can be a regexp). Do not forget that po4a considers the  translated  document  here.  This
       documentation is in English, but your line should probably read as follows if you intend your addendum to
       apply to the French translation of the document.

        PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>

       Once the "position" is found in the target document, po4a searches for the next line after the "position"
       that matches the provided "endboundary". The addendum is added right after that line (because we provided
       an endboundary, i.e. a boundary ending the current section).

       The exact same effect could be obtained with the following header, that is equivalent:

        PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>

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

       You  can  also  set  the  insertion  mode  to  the  value  "before",  with  a similar semantic: combining
       "mode=before" with an "endboundary" will put the addendum just after the matched boundary, that the  last
       potential  boundary  line before the "position". Combining "mode=before" with an "beginboundary" will put
       the addendum just before the  matched  boundary,  that  the  last  potential  boundary  line  before  the
       "position".

         Mode   | Boundary kind |     Used boundary      | Insertion point compared to the boundary
        ========|===============|========================|=========================================
        'before'| 'endboundary' | last before 'position' | Right after the selected boundary
        'before'|'beginboundary'| last before 'position' | Right before the selected boundary
        'after' | 'endboundary' | first after 'position' | Right after the selected boundary
        'after' |'beginboundary'| first after 'position' | Right before the selected boundary
        'eof'   |   (none)      |  n/a                   | End of file

       Hint and tricks about addenda

       •   Remember  that  these are regexp. For example, if you want to match the end of a nroff section ending
           with the line ".fi", do not use ".fi" as endboundary, because it will match with "the[ fi]le",  which
           is obviously not what you expect. The correct endboundary in that case is: "^\.fi$".

       •   White  spaces  ARE  important  in  the content of the "position" and boundaries. So the two following
           lines are different. The second one will only be found if there is  enough  trailing  spaces  in  the
           translated document.

            PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>
            PO4A-HEADER: position=About this document ; mode=after; beginboundary=<section>

       •   Although  this  context  search  may  be considered to operate roughly on each line of the translated
           document, it actually operates on the internal data string of the translated document. This  internal
           data  string  may be a text spanning a paragraph containing multiple lines or may be a XML tag itself
           alone. The exact insertion point of the addendum must be before or after the internal data string and
           can not be within the internal data string.

       •   Pass the -vv argument to po4a to understand how the addenda are added to the translation. It may also
           help to run po4a in debug mode to see the actual internal data string when  your  addendum  does  not
           apply.

       Addenda examples

       •   If you want to add something after the following nroff section:

             .SH "AUTHORS"

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

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

       •   If you want to add something right after a given line (e.g. after the line "Copyright Big Dude"), use
           a position matching this line, mode=after and give a beginboundary matching any line.

            PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^

       •   If  you  want  to add something at the end of the document, give a position matching any line of your
           document (but only one line. Po4a won't proceed if it's not unique), and give an endboundary matching
           nothing. Don't use simple strings here like "EOF", but prefer those which have less chance to  be  in
           your document.

            PO4A-HEADER:mode=after;position=About this document;beginboundary=FakePo4aBoundary

       More detailed example

       Original document (POD formatted):

        |=head1 NAME
        |
        |dummy - a dummy program
        |
        |=head1 AUTHOR
        |
        |me

       Then,  the following addendum will ensure that a section (in French) about the translator is added at the
       end of the file (in French, "TRADUCTEUR" means "TRANSLATOR", and "moi" means "me").

        |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
        |
        |=head1 TRADUCTEUR
        |
        |moi
        |

       To put your addendum before the AUTHOR, use the following header:

        PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1

       This works because  the  next  line  matching  the  beginboundary  /^=head1/  after  the  section  "NAME"
       (translated  to  "NOM" in French), is the one declaring the authors. So, the addendum will be put between
       both sections. Note that if another section is added between NAME and AUTHOR sections  later,  po4a  will
       wrongfully put the addenda before the new section.

       To avoid this you may accomplish the same using mode=before:

        PO4A-HEADER:mode=before;position=^=head1 AUTEUR

How does it work?

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

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

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

          Input document --\                             /---> Output document
                            \      TransTractor::       /       (translated)
                             +-->--   parse()  --------+
                            /                           \
          Input PO --------/                             \---> Output PO
                                                                (extracted)

       This little bone is the core of all the po4a architecture. If you  omit  the  input  PO  and  the  output
       document,  you  get  po4a-gettextize.  If  you  provide  both  input and disregard the output PO, you get
       po4a-translate. The po4a calls TransTractor twice  and  calls  msgmerge  -U  between  these  TransTractor
       invocations   to   provide   one-stop   solution   with   a   single   configuration  file.   Please  see
       Locale::Po4a::TransTractor(3pm) for more details.

Open-source projects using po4a

       Here is a very partial list of projects that use po4a in production for their documentation. If you  want
       to add your project to the list, just drop us an email (or a Merge Request).

       •   adduser (man): users and groups management tool.

       •   apt (man, docbook): Debian package manager.

       •   aptitude (docbook, svg): terminal-based package manager for Debian

       •   F-Droid  website <https://gitlab.com/fdroid/fdroid-website> (markdown): installable catalogue of FOSS
           (Free and Open Source Software) applications for the Android platform.

       •   git <https://github.com/jnavila/git-manpages-l10n> (asciidoc): distributed version-control system for
           tracking changes in source code.

       •   Linux manpages <https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (man)

           This project provides an infrastructure for translating many manpages to different  languages,  ready
           for integration into several major distributions (Arch Linux, Debian and derivatives, Fedora).

       •   Stellarium <https://github.com/Stellarium/stellarium> (HTML): a free open source planetarium for your
           computer. po4a is used to translate the sky culture descriptions.

       •   Other        item        to        sort        out:       <https://gitlab.com/fdroid/fdroid-website/>
           <https://github.com/fsfe/reuse-docs/pull/61>

FAQ

   How do you pronounce po4a?
       I personally vocalize it as pouah <https://en.wiktionary.org/wiki/pouah>, which is a French onomatopoetic
       that we use in place of yuck :) I may have a strange sense of humor :)

   What about the other translation tools for documentation using gettext?
       There are a few of them. Here is a possibly incomplete list, and more tools are coming at the horizon.

       poxml
           This is the tool developed by KDE people to handle DocBook XML. AFAIK, it was the  first  program  to
           extract strings to translate from documentation to PO files, and inject them back after translation.

           It  can  only  handle  XML,  and only a particular DTD. I'm quite unhappy with the handling of lists,
           which end in one big msgid. When the list become big, the chunk becomes harder to swallow.

       po-debiandoc
           This program done by Denis Barbier is a sort of precursor of the po4a SGML module, which more or less
           deprecates it. As the name says, it handles  only  the  DebianDoc  DTD,  which  is  more  or  less  a
           deprecated DTD.

       xml2po.py
           Used  by the GIMP Documentation Team since 2004, works quite well even if, as the name suggests, only
           with XML files and needs specially configured makefiles.

       Sphinx
           The  Sphinx  Documentation  Project  also  uses  gettext  extensively  to  manage  its  translations.
           Unfortunately,  it  works  only for a few text formats, rest and markdown, although it is perhaps the
           only tool that does this managing the whole translation process.

       The main advantages of po4a over them are the ease of extra content addition (which is even worse  there)
       and the ability to achieve gettextization.

   SUMMARY of the advantages of the gettext based approach
       • The  translations  are  not  stored  along  with  the  original,  which  makes it possible to detect if
         translations become out of date.

       • The translations are stored in separate files from each other, which prevents translators of  different
         languages from interfering, both when submitting their patch and at the file encoding level.

       • It  is  based  internally on gettext (but po4a offers a very simple interface so that you don't need to
         understand the internals to use it).  That way, we don't have to re-implement the wheel, and because of
         their wide use, we can think that these tools are more or less bug free.

       • Nothing changed for the end-user (beside the fact translations will hopefully  be  better  maintained).
         The resulting documentation file distributed is exactly the same.

       • No  need  for  translators to learn a new file syntax and their favorite PO file editor (like Emacs' PO
         mode, Lokalize or Gtranslator) will work just fine.

       • gettext offers a simple way to get statistics about what is done, what should be reviewed and  updated,
         and what is still to do. Some example can be found at those addresses:

          - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
          - http://www.debian.org/intl/l10n/

       But everything isn't green, and this approach also has some disadvantages we have to deal with.

       • Addenda are… strange at the first glance.

       • You  can't  adapt the translated text to your preferences, like splitting a paragraph here, and joining
         two other ones there. But in some sense, if there is an issue with the original, it should be  reported
         as a bug anyway.

       • Even with an easy interface, it remains a new tool people have to learn.

         One  of  my  dreams would be to integrate somehow po4a to Gtranslator or Lokalize. When a documentation
         file is opened, the strings are automatically extracted, and a translated file + po file can be written
         to disk. If we manage to do an MS Word (TM) module (or at least RTF) professional translators may  even
         use it.

SEE ALSO

       •   The documentation of the all-in-one tool that you should use: po4a(1).

       •   The   documentation   of   the   individual   po4a   scripts:  po4a-gettextize(1),  po4a-updatepo(1),
           po4a-translate(1), po4a-normalize(1).

       •   The additional helping scripts: msguntypot(1), po4a-display-man(1), po4a-display-pod(1).

       •   The parsers  of  each  formats,  in  particular  to  see  the  options  accepted  by  each  of  them:
           Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm), Locale::Po4a::Guide(3pm), Locale::Po4a::Ini(3pm),
           Locale::Po4a::KernelHelp(3pm),           Locale::Po4a::Man(3pm),          Locale::Po4a::RubyDoc(3pm),
           Locale::Po4a::Texinfo(3pm),            Locale::Po4a::Text(3pm),             Locale::Po4a::Xhtml(3pm),
           Locale::Po4a::Yaml(3pm),            Locale::Po4a::BibTeX(3pm),            Locale::Po4a::Docbook(3pm),
           Locale::Po4a::Halibut(3pm),             Locale::Po4a::LaTeX(3pm),             Locale::Po4a::Pod(3pm),
           Locale::Po4a::Sgml(3pm), Locale::Po4a::TeX(3pm), Locale::Po4a::Wml(3pm), Locale::Po4a::Xml(3pm).

       •   The   implementation   of  the  core  infrastructure:  Locale::Po4a::TransTractor(3pm)  (particularly
           important to understand the code  organization),  Locale::Po4a::Chooser(3pm),  Locale::Po4a::Po(3pm),
           Locale::Po4a::Common(3pm). Please also check the CONTRIBUTING.md file in the source tree.

AUTHORS

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

Po4a Tools                                         2023-01-03                                            PO4A(7)