Provided by: po4a_0.41-1_all bug

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