1PO4A-RUNTIME.7(7) User Contributed Perl Documentation PO4A-RUNTIME.7(7)
2
6 po4a-runtime - po4a and runtime gettext translation without Autotools
7
9 With po4a-build, po4a also includes support for adding translation of
10 runtime script output messages using gettext but without requiring the
11 package to adopt Autotools and the typical ./configure process.
12 Using example Makefile snippets, packages can harness intltool with
14 minimal effort.
15
17 Documentation translation should NOT use the same po/ directory as the
18 runtime translation. Whilst runtime translation can use directories
19 other than po/, it is usually easiest to go with the convention.
20
22 Just a word on packages that use scripts in multiple programming
23 languages. A common mix is Perl and shell. Note bene: gettext WILL get
24 confused and omit strings from one or other language unless file
25 extensions are used for whichever is the least problematic language.
26 When using multiple languages, experiment with various settings in
28 po/Makevars until you get all the strings you need in the POT file.
29 In particular, specifying two languages in po/Makevars can be
31 problematic. Instead of:
32 # Don't do this:
34 XGETTEXT_OPTIONS = -L Perl -L Shell --from-code=iso-8859-1
35 Consider renaming (or providing symlink(s) for) all files for one of
37 the languages involved and omitting the explicit -L options. The file
38 extension only needs to exist during the time that po/POTFILES.in is
39 being processed.
40 The --keywords option can also be useful - see the xgettext
42 documentation.
43
45 So, create your top level po/ directory and then use the example files
46 in /usr/share/doc/po4a/examples/ to populate it.
47 LINGUAS
49 Must exist, even if empty. Consists of a list of translations -
50 each line not starting with a '#' must match an existing PO file.
51 e.g. if LINGUAS contains a single line, 'fr', an fr.po file must
52 exist alongside the LINGUAS file.
53 $ cat po/LINGUAS
55 cs
56 de
57 fr
58 $
59 By convention, the LINGUAS file is sorted alphabetically but that
61 is a manual process.
62 POTFILES.in
64 The list of files containing the messages that need to be
65 translated at runtime - i.e. your scripts. If you've used the top
66 level po/ directory, the paths should be relative to the top level
67 directory, not the po/ directory itself.
68 $ ls -l
70 myscript.pl
71 another.pl
72 foo/support.pl
73 po/
74 po/POTFILES.in
75 $ cat po/POTFILES.in
76 myscript.pl
77 another.pl
78 foo/support.pl
79 $
80 Note that it is explicitly supported that the scripts themselves
82 can contain strings for both runtime and documentation translation,
83 e.g. using gettext functions for runtime and embedded POD content
84 for documentation. So it is not a problem to have the same file
85 listed in po/POTFILES.in and doc/po4a-build.conf
86 Makevars-perl.example
88 If your scripts are in Perl, copy this example file as po/Makevars
89 and edit it to suit.
90 Makevars-shell.example
92 If your scripts are in shell, copy this example file as po/Makevars
93 and edit it to suit.
94 po4a-build.make
96 Copy this example file as po/Makefile - it shouldn't need editing
97 but you may want to keep it updated against
98 /usr/share/doc/po4a/examples/po4a-build.make as it may need to be
99 updated within po4a releases as the underlying intltool support
100 changes. (The file itself was generated from another project using
101 Autotools and intltool.)
102
104 These snippets need to be added to your top level Makefile or whatever
105 other method you use to prepare your sources for distribution.
106 clean:
108 $(MAKE) -C po/ clean
109 install:
111 $(MAKE) -C po/ install DESTDIR=$(DESTDIR)
112 dist:
114 $(MAKE) -C po/ pot
115 (In an Autotools project, this would happen automatically by simply
117 adding po to the "SUBDIRS" value in Makefile.am.)
118
120 Runtime translation isn't quite as easy as po4a-build in that adding a
121 new translation does require editing po/LINGUAS, but apart from that,
122 updating translations is merely a case of replacing the relevant PO
123 file with the new version.
124 Depending on how you prepare your source tarball, you may also need to
126 list new PO files in the MANIFEST file or add to the script(s) that
127 prepare the tarball. (That also applies to po4a-build.)
128 Any *.mo or *.gmo files in po/ can be deleted / cleaned up.
130
132 Whilst the example files are part of the po4a project, you are free to
133 use, modify and distribute them in your own projects without needing to
134 refer back to po4a or list the po4a team in your own copyright notices,
135 in the same manner as other build tools like Automake itself. If you
136 want to mention po4a, that is fine too.
137
139 Neil Williams <linux@codehelp.co.uk>
140perl v5.12.2 2010-12-01 PO4A-RUNTIME.7(7)