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>