Overview
This section provides a description of the gettext support integrated in htmltmpl. It's of interest for those who want to use htmltmpl to build a multilingual web application.
Only the gettext support in htmltmpl is desribed here. Please refer to other sources for general information on gettext and its usage. The info manual page for gettext should be included in all modern UNIX distributions.
The gettext support in htmltmpl must be explicitly activated by setting the parameter gettext of the TemplateManager or the TemplateCompiler constructor to TRUE.
The support will not work if your computer's locale system is not installed and configured properly or if your Python or PHP interpreter is not configured to support locales and gettext. In Python, gettext modules are in the standard library. PHP must be compiled with the --with-gettext parameter, otherwise an attempt to use htmltmpl in gettext mode will result in a "call to undefined function" error.
Syntax
The strings to be translated by gettext must be enclosed in double brackets. For example:
<TMPL_LOOP Test>
[[Product]]: <TMPL_VAR product><br>
[[Price]]: <TMPL_VAR price><br>
</TMPL_LOOP>
The brackets will be removed when the template is processed. If you need to include opening brackets somewhere in the fixed text of the template then you can escape them using a backslash. In the following example the brackets will not be removed and the word 'jumps' will not be translated. The backslash is only removed when it is placed right before the opening or closing double brackets.
Quick brown fox \[[jumps]] over a lazy dog.
Sometimes we need to use the backslash '\'.
... will be printed as:
Quick brown fox [[jumps]] over a lazy dog.
Sometimes we need to use the backslash '\'.
In some rare cases you need to print a backslash right before double brackets, then you can use another backslash to escape the backslash to be printed. In that case, one backslash will be printed and the translation will take place. In the following example the word 'jumps' will be translated:
Quick brown fox \\[[jumps]] over a lazy dog.
... will be printed as:
Quick brown fox \jumps over a lazy dog.
The backslash can also be used to include closing double brackets in a text which should be translated. In the following example, the double brackets are taken as a part of the text to be translated. That means that the whole string 'jumps over ]] a lazy' will be passed to gettext for translation.
Quick brown fox [[jumps over \]] a lazy]] dog.
A backslash always escapes another backslash. That means that in order to print two backslashes you must write four of them. An example:
This will print one backslash: \.
This will print one backslash: \\.
This will print two backslashes: \\\\.
... will be printed as:
This will print one backslash: \.
This will print one backslash: \.
This will print two backslashes: \\.
Newlines and leading whitespace can be included in the bracketed strings and will be removed before the string is passed to gettext.
The following:
[[Gunmen attacked Hurriyah, a Sunni Arab area of Baghdad,
burning mosques and homes, with at least 30 people reported killed,
according to police officials.]]
will be passed to gettext as one long line with the newlines
and the leading whitespace all replaced with one space.
tmpl-xgettext.pl
The gettext strings are usually extracted by the xgettext utility, which is distributed with the gettext library, but this utility does not work with htmltmpl templates. You must use the tmpl-xgettext.pl script from the htmltmpl distribution in order to convert the templates into a format that xgettext can work with.
cat template.tmpl | perl tmpl-xgettext.pl | xgettext -o file.po -
Programming
Your program must initialize gettext before it calls the process() method of the TemplateProcessor. It usually means to call setlocale(), bindtextdomain() and textdomain() with the appropriate parameters. Check out the documentation of PHP and Python gettext extensions for more information.
Your program is responsible for translation of the strings that are assigned as values to TMPL_VARs.