Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PO4A-RUNTIME(7)			  Po4a Tools		       PO4A-RUNTIME(7)

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			  2021-02-28		       PO4A-RUNTIME(7)

NAME | Introduction | Layout | Multiple languages | Populating po/ | Building | Maintenance | Copyright | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=po4a-runtime&sektion=7&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help