Report Generator - Administration Guide : Internationalization (i18n)

1. i18n

This chapter and sub-chapters discusses the i18n capabilities of the Report Generator and how to solve requirements related to creating reports in multiple languages.

1.1. Stylesheets

The stylesheets are responsible for the layout and placement of data including adding labels in different places such as

header
footer
form labels
table-headers
…

In order to avoid hard-coding labels within the stylesheet, one can define variables in the XSLT like this:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:fo="http://www.w3.org/1999/XSL/Format">

  <xsl:variable name="label_Files" select="'Files'" /> (1)
  <xsl:variable name="label_Issues">Issues</xsl:variable> (2)
  ...
  <xsl:template>
    <fo:block>
      <xsl:value-of select="$label_Files" /> (3)
    </fo:block>
  </xsl:template>
</xsl:stylesheet>

1	Declares variables containing the static text
2	Alternative syntax
3	Using the variable with `<xsl:value-of>`

The next step is to separate the logic from the declaration of the variables in order to support multiple languages.

1.1.1. Dynamic Choose of Stylesheet

Within the Report definition you define the stylesheet to be used using the <Stylesheet> element. E.g.

<AdvancedReport>
  <Stylesheet>Name-of-Stylesheet.xsl</Stylesheet>
  ...
</AdvancedReport>

At runtime when the report is being created and the stylesheets are being resolved, they are resolved based upon the locale used when the report is being invoked. Many times this is the locale as the user has, however, the user may choose another locale (see chapter below).

Example: A french speaking user located in Canada has the locale fr_CA is about to create a report. When the stylesheet is resolved, the search order for the stylesheet to be used will in this case be:

Name-of-Stylesheet_fr_CA.xsl
Name-of-Stylesheet_fr.xsl
Name-of-Stylesheet.xsl

The first found will be used.

Hence, within the language specific stylesheets, you can declare all your language specific variables and then finally include the language neutral templates that produces the output.

Example:

Name-of-Stylesheet_fr_CA.xsl

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:fo="http://www.w3.org/1999/XSL/Format">

  <xsl:variable name="label_Files">Fichiers</xsl:variable>
  <xsl:variable name="label_Issues">Problèmes</xsl:variable>
  <!-- add more variables ... -->

  <!-- Include layout / templates -->
  <xsl:include href="tvc:stylesheet/Layout.xsl"/>
</xsl:stylesheet>

1.2. Extracted Data

If you are using the default XML format as produced from the Report Generator, you will in many places be able to automatically get the correct translation of for example attribute names, state names, type names etc.

NOTE For this to work, the translation must exist in the language specific properties files below /WEB-INF/classes in your application.

Example output:

Header part of a section

<header id="c4" type="string">
    <name>State</name>
    <label>État</label> (1)
    <expression>current</expression>
    <setting name="Registered Suite">Framework</setting>
</header>

1	The label is here translated into French

Object part of a section

<objects>
  <row ...>
      <cell index="0" colRef="c0">
          <value>Pièce Attache</value> (1)
      </cell>
      ...
      <cell index="4" colRef="c4">
          <value>Créée</value> (2)
      </cell>
  </row>

1	The type translated into French
2	The current state name in French

Meta Section

  <attr key="Part Classification"
      symbolicName="attribute_Classification"
      localizedKey="Classification de pièces"
      value="Unassigned">Non affecté</attr> (1)

  <basic key="current" localizedKey="État" value="Create">Créée</basic>

1	Both the translated value and the DB-value is available in the output

1.3. Designing Your Tables

You typically use tables that are evaluated over a set of objects and/or relationships. A table defines columns, where each column typically contains a select expression.

To ensure that translations are working, you must set the Setting "Registered Suite" on the column and also use the correct keys for the Labels (also Alt if used). Example:

<?xml version="1.0" encoding="UTF-8"?>
<Table xmlns="http://technia.com/TVC/Table" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://technia.com/TVC/Table http://products.technia.com/tvc/schema/latest/Table.xsd">
	<Column>
		<Name>Type</Name>
		<Expression>type</Expression>
		<Label>emxFramework.Basic.Type</Label>
		<RegisteredSuite>Framework</RegisteredSuite>
	</Column>
	<Column>
		<Name>Name</Name>
		<Expression>name</Expression>
		<Label>emxFramework.Basic.Name</Label>
		<RegisteredSuite>Framework</RegisteredSuite>
	</Column>
	<Column>
		<Name>Revision</Name>
		<Expression>revision</Expression>
		<Label>emxFramework.Basic.Revision</Label>
		<RegisteredSuite>Framework</RegisteredSuite>
	</Column>
	<Column>
		<Name>Description</Name>
		<Expression>description</Expression>
		<Label>emxFramework.Basic.Description</Label>
		<RegisteredSuite>Framework</RegisteredSuite>
	</Column>
	<Column>
		<Name>Current</Name>
		<Expression>current</Expression>
		<Label>emxFramework.Basic.Current</Label>
		<RegisteredSuite>Framework</RegisteredSuite>
	</Column>
</Table>

1.4. Change Language

By default, the report is created with the same locale information as the user who is requesting the report. Note however that in some cases, the user may want to create a report in a different language.

To support that use case you need to decide where to do the language selection. Typically you have two options; either associate the report with a pre-process-page and include a language chooser in there. OR, provide different commands / links that will launch the Report Generator with different values for the locale/language.

1.4.1. Request Parameter

If you are launching the report generator through a direct link or via a command in a toolbar, you are most likely using the following URL:

${ROOT_DIR}/tvc-action/beginCreateReport?reportDefinition=tvc:report/MyReport.xml

By adding the parameter "locale" with a valid value, you can create multiple versions of such link/command. Example:

${ROOT_DIR}/tvc-action/beginCreateReport?reportDefinition=tvc:report/MyReport.xml&locale=fr_CA

1.4.2. Pre Process Page

To support selecting the locale/language from a pre-process page, you need to in the pre-process page include a language chooser.

Example of such here:

Pre process page with language chooser

...
<html>
    ...
    <body onload="pageInit()">
        <form action="<rg:writePreProcessPageSubmitAction/>"
              method="post" style="margin:0px;padding:0px;">
            <table>
                <tr>
                    <td class="label" nowrap>Choose Language</td>
                    <td class="inputField">
                        <select name="locale"> (1)
                            <option value="en_US">English (US)</option>
                            <option value="de_DE">German (Germany)</option>
                            <option value="fr_FR">French (France)</option>
                            <option value="fr_CA">French (Canada)</option>
                        </select>
                    </td>
                </tr>
            </table>
        </form>
    </body>
</html>

1	The selected value is submitted with the name "locale"

1.4.3. Trigger Invokation

When invoked via a trigger, one can override the locale via adding a parameter like this -locale=fr.

<MQL> execute program TVCReportGenerator –method mxMain -report=R-002 -oid=1234.5678.90123.4567 -locale=fr_CA;