Chapter 3. Localisation (l10n) and customisation of stylesheet output.

Where possible, each stylesheet supports providing translatable strings and user-specific encodings via external parameters. This can make the command line very long so is best performed using a script. Each descriptive word in the output is configured as a string parameter for the stylesheet and can be replaced with a translated version. HTML output supports setting the HTML language (as would be specified in the <html> lang attribute) and the encoding (as would be specified in the <meta> charset value in the content attribute).

If you use these stylesheets via a scripting language - like bash, PHP or Perl - you could automate the translation by passing values obtained from a normal gettext PO file. Copy the translatable strings into your script file as normal variables then mark up those variables for translation by gettext. When the script is called, gettext will assign the translated values to the variables and your script can simply echo those values to the calls to the XSL parser routines.

It is important that the HTML language and the encoding match each other AND the expected content of the HTML output generated from the pilot-qof data.

When providing translated strings, the same constraints apply as if you were using gettext and a normal PO file: the context and format of the translation should match the intention expressed in the default value of the parameter. If the default is plural, the translation should be plural. If the default is capitalised, the translation should be capitalised - subject to grammatical rules for that language - even if the parameter name itself is not capitalised.

Each stylesheet specifies the translatable strings in a block near the top of the file, marked as for the attention of translators. Common settings, like the HTML language parameter and the encoding support, are in the pilot-qof-std.xsl stylesheet and are available in all HTML stylesheets by using the string parameters html_lang and encoding.

Examples. Convert a QSF XML file containing pilot_address records, into individual VCard .vcf files in the vcards/ directory - which must already exist. Files are named according to either the Company or FirstName_LastName of the pilot_address record.

Example 3.1. Using XSL to create vcard output from a QSF XML file

$ xsltproc --nonet -o vcards/ http://www.data-freedom.org/xsl/pilot-qof-address-vcard1.xsl addresses.xml
      


Convert the output from pilot-qof --invoice-city or --invoice-vendor options into an HTML invoice. The invoice uses CSS in the invoice.css file. This stylesheet needs records from pilot_address, pilot_expenses and pilot_datebook databases but ignores pilot_todo records that may be present. Calendar data is used to create the main invoice, expenses from the same day are added and address data is added to describe the invoice.

Example 3.2. Using XSL to create invoices by collating data

$ xsltproc --nonet -o invoices/ http://www.data-freedom.org/xsl/pilot-qof-invoice-xhtml.xsl invoice.xml
      


This example overrides the default mileage-rate (0.30 currency units per unit distance) and the default hourly-rate (20 currency units per hour) provided by the stylesheet with user specific values.

Example 3.3. Customising invoice rates

$ xsltproc --nonet --stringparam mileage-rate 0.45 --stringparam hourly-rate 21 \
-o invoices/ http://www.data-freedom.org/xsl/pilot-qof-invoice-xhtml.xsl invoice.xml
      


The stylesheet currently defaults to Pounds Sterling and - depending on support in your shell - the currency-symbol can also be overridden:

Example 3.4. Customising invoice currency.

$ xsltproc --nonet --stringparam currency-symbol $ \
-o invoices/ http://www.data-freedom.org/xsl/pilot-qof-invoice-xhtml.xsl invoice.xml
      


If your shell complains about using a currency-symbol on the command line, e.g. when trying to use Euro (€), copy the stylesheet to somewhere below your /home/ directory and edit the currency-symbol in the file. Wikipedia has a reasonably complete list of entity references: http://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references