htmltmpl: templating engine for separation of code and HTML

This section is a description of the gettext support integrated in htmltmpl. It's of interest for anyone who would like to use htmltmpl to easily build a multilingual web application.

The section describes only the gettext support in htmltmpl. Please refer to other sources for general info on gettext and its principles. The info manual for gettext should be included in every modern UNIX distribution.

The gettext support in htmltmpl must be explicitely activated by setting the parameter 'gettext' of TemplateManager or TemplateCompiler constructor to TRUE.

The support will not work if your computer's locale system is not installed properly or if your Python or PHP interpreter is not configured to support locales and gettext. In Python, gettext support is part of the standard library. PHP must be compiled using the '--with-gettext' parameter, otherwise an attempt to use htmltmpl in gettext mode will result in a "call to undefined function" error.

Syntax

In the templates, all text which should be translated by gettext must be enclosed in double brackets. 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 text of the template, 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 will be removed always and only when it is placed right before 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.
    Sometims we need to use the backslash '\'.

In some rare cases you need to print a backslash right before double brackets. You can use another backslash to escape the backslash. 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, the whole text 'jumps over ]] a lazy' will be translated. 

    Quick brown fox [[jumps over \]] a lazy]] dog.

A backslash always escapes another backslash. That means that 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: \\.

tmpl-xgettext

The gettext strings must usually be extracted using the xgettext program. The standard xgettext program cannot work with htmltmpl templates, though. You must use the tmpl-xgettext.pl script which is included in htmltmpl distribution to convert the templates into a format which xgettext can understand. 

    cat template.tmpl | perl tmpl-xgettext.pl | xgettext -o file.po -

Programming

Your program must initialize gettext before it calls the process() method of TemplateProcessor. It usually means to call setlocale(), bindtextdomain() and textdomain() with appropriate parameters. Check documentation of PHP or Python gettext extensions for more information.

Also, your program is of course responsible for translation of any texts which are assigned as values to TMPL_VARs.