---
name: "po4a-runtime"
section: "7"
platform: "linux"
package: "po4a"
version: "0.47-2"
release: "Debian 9 (Stretch)"
platforms: ["linux"]
url: "https://new.carta.tech/po4a-runtime"
---

# po4a-runtime(7)

po4a and runtime gettext translation without Autotools

## 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)](/xgettext/1.md) 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>
```