NAME

       po4a-runtime - po4a and runtime gettext translation without Autotools

Introduction

       With po4a-build, po4a also includes support for adding translation of runtime script output messages
       using gettext but without requiring the package to adopt Autotools and the typical ./configure process.

       Using example Makefile snippets, packages can harness intltool with minimal effort.

Layout

       Documentation translation should NOT use the same po/ directory as the runtime translation. Whilst
       runtime translation can use directories other than po/, it is usually easiest to go with the convention.

Multiple languages

       Just a word on packages that use scripts in multiple programming languages. A common mix is Perl and
       shell. Note bene: gettext WILL get confused and omit strings from one or other language unless file
       extensions are used for whichever is the least problematic language.

       When using multiple languages, experiment with various settings in po/Makevars until you get all the
       strings you need in the POT file.

       In particular, specifying two languages in po/Makevars can be problematic. Instead of:

        # Don't do this:
        XGETTEXT_OPTIONS = -L Perl -L Shell --from-code=iso-8859-1

       Consider renaming (or providing symlink(s) for) all files for one of the languages involved and omitting
       the explicit -L options. The file extension only needs to exist during the time that po/POTFILES.in is
       being processed.

       The --keywords option can also be useful - see the xgettext(1) documentation.

Populating po/

       So, create your top level po/ directory and then use the example files in /usr/share/doc/po4a/examples/
       to populate it.

       LINGUAS
           Must  exist,  even  if  empty. Consists of a list of translations - each line not starting with a '#'
           must match an existing PO file.  E.g. if LINGUAS contains a single line, 'fr',  an  fr.po  file  must
           exist alongside the LINGUAS file.

            $ cat po/LINGUAS
            cs
            de
            fr
            $

           By convention, the LINGUAS file is sorted alphabetically but that is a manual process.

       POTFILES.in
           The  list of files containing the messages that need to be translated at runtime - i.e. your scripts.
           If you've used the top level po/ directory, the paths should be relative to the top level  directory,
           not the po/ directory itself.

            $ ls -l
            myscript.pl
            another.pl
            foo/support.pl
            po/
            po/POTFILES.in
            $ cat po/POTFILES.in
            myscript.pl
            another.pl
            foo/support.pl
            $

           Note that it is explicitly supported that the scripts themselves can contain strings for both runtime
           and documentation translation, e.g.  using gettext functions for runtime and embedded POD content for
           documentation.  So  it  is  not  a  problem  to  have  the  same  file  listed  in po/POTFILES.in and
           doc/po4a-build.conf

       Makevars-perl.example
           If your scripts are in Perl, copy this example file as po/Makevars and edit it to suit.

       Makevars-shell.example
           If your scripts are in shell, copy this example file as po/Makevars and edit it to suit.

       po4a-build.make
           Copy this example file as po/Makefile - it shouldn't need editing but you may want to keep it updated
           against /usr/share/doc/po4a/examples/po4a-build.make as  it  may  need  to  be  updated  within  po4a
           releases  as  the  underlying  intltool  support changes. (The file itself was generated from another
           project using Autotools and intltool.)

Building

       These snippets need to be added to your top level Makefile or whatever other method you  use  to  prepare
       your sources for distribution.

        clean:
               $(MAKE) -C po/ clean

        install:
               $(MAKE) -C po/ install DESTDIR=$(DESTDIR)

        dist:
               $(MAKE) -C po/ pot

       (In  an  Autotools project, this would happen automatically by simply adding po to the "SUBDIRS" value in
       Makefile.am.)

Maintenance

       Runtime translation isn't quite as easy as po4a-build in that  adding  a  new  translation  does  require
       editing po/LINGUAS, but apart from that, updating translations is merely a case of replacing the relevant
       PO file with the new version.

       Depending  on how you prepare your source tarball, you may also need to list new PO files in the MANIFEST
       file or add to the script(s) that prepare the tarball. (That also applies to po4a-build.)

       Any *.mo or *.gmo files in po/ can be deleted / cleaned up.

Copyright

       Whilst the example files are part of the po4a project, you are free to use, modify and distribute them in
       your own projects without needing to refer back to po4a or list the  po4a  team  in  your  own  copyright
       notices, in the same manner as other build tools like Automake itself.  If you want to mention po4a, that
       is fine too.

AUTHORS

        Neil Williams <linux@codehelp.co.uk>

Po4a Tools                                         2017-08-26                                    PO4A-RUNTIME(7)