Translation Engine Concepts
English | Translate this article...
About this document
In this document we will explain the way translations are handled by Openbravo, giving special focus to the file structure to store the translations and how Modularity affects the translation process. The article gives the necessary background to understand the Openbravo's translation engine and it is recommended to read it before starting any translation effort.
Remember that this document is written from a theoretical perspective. If you just want to start translating without knowing the underneath details of the Openbravo translation engine, you can safely go to the How to Create and Update Translation Modules document.
Openbravo is a software that supports translations from the very beginning. Everything related to the User Interface can be translated: Windows, Tabs, Fields, Labels, Reports, Menu entries, Messages, Descriptions, Helps, etc. And even Masterdata can also be translated, like Country or Currency names. That means the full ERP is ready to be translated.
Translations are distributed inside a set of XML files with a simple structure. Each XML file represents an Application Dictionary table that can be translated; this kind of tables always have a _TRL suffix (see Multi-Language and Translations - TRL_Tables for more info).
The XML files are included into the corresponding translation module and make it easier for the user to install them into any Openbravo instance.
Modularity and Translations
Since 2.50 version, Openbravo supports the concept of module that extends the base ERP functionality. That usually means these modules add new User Interface elements which need to be translated, like for example messages, labels or menu entries. We can identify this kind of modules because they have the Translation Required flag set to Yes inside its module's definition, that represents they can be translated.
The translation of any module is done through another module containing its translation files for the desire language and that depends on the original one (see How to create and update translation modules – Create a translation module for details).
So what it's important to understand is that, in a modular environment, it is necessary to translate all the modules included in our instance to have a fully translated ERP, which means creating a translation module for each original module which has the Translation Required flag set to Yes.
XML translation file structure
The structure of the XML translation files in Openbravo, which is based in the Compiere's one, is as follows:
- A root tag, called compiereTrl, containing the table and the language names.
- For each row in the table there will be a row tag with attributes id for the row identification and trl which will be Y or N depending on whether or not it has been fully translated.
- Inside the row tag, there is a value tag for each column in the table. This tag includes the attributes column for the column name, original signifying the value for the column in the base language, and isTrl similar to the row's trl but in this case at value's level. The value for the tag will contain the translated text. This is the text that you have to change if you want to make a translation.
The following piece of code is an example for the AD_ELEMENT_TRL table translated into Spanish (Spain):
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <compiereTrl baseLanguage="en_US" language="es_ES" table="AD_ELEMENT" version=""> <row id="0131585AC1F246DBAF6B84E53534F5FA" trl="Y"> <value column="Name" isTrl="Y" original="Accounting Schema Currency Credit">Moneda del Esquema Contable para el Haber</value> <value column="PrintName" isTrl="Y" original="Accounting Schema Currency Credit">Moneda del Esquema Contable para el Haber</value> <value column="Description" isTrl="Y" original="The amount credited to an account, converted to the organization default currency.">El importe abonado (haber) a una cuenta convertido a la moneda por defecto de la organización.</value> <value column="Help" isTrl="Y" original="The Account Credit Amount indicates the transaction amount converted to this organization's accounting currency">Refleja el importe de la transacción (haber) convertido a la moneda del esquema contable de la organización</value> <value column="PO_Description" isTrl="N" original=""/> <value column="PO_Help" isTrl="N" original=""/> <value column="PO_Name" isTrl="N" original=""/> <value column="PO_PrintName" isTrl="N" original=""/> </row>
As you can imagine, this XML files are automatically generated by Openbravo, so you don't need to manually create them, but just translating the value tag as we have seen in the example.
Set of translation files
The Export Translations process is in charge of creating the Openbravo's XML translation files. Each file represents an Application Dictionary table related to the User Interface and, therefore, contains strings which can be translated. The name of each XML file has the following structure: <table name>_TRL_<ISO language>_<ISO country>.xml. Example AD_ELEMENT_TRL_es_ES.xml that contains the translation into Spanish (Spain) for the AD_ELEMENT table.
In order to create a high quality translation, it is very important to understand the kind of information stored in each table/file. Here is the list of tables involved into the translation in alphabetical order:
- AD_ELEMENT: Probably the most important table from a User Interface perspective. It is associated with the Element window inside the Application Dictionary. It contains all the elements of the application, which are used in order to have centrally maintained descriptions and helps displayed into the fields.
- AD_FIELDGROUP: It is associated with the Field Category window inside the Application Dictionary. Field categories are used to group fields inside windows.
- AD_FIELD: It represents the fields inside a tab. The XML files associated with this table only contain the fields that are not centrally maintained, i.e. the ones that don't inherit the information from their elements.
- AD_FORM: It stores the name, description and help for the manually generated windows, i.e. the windows not automatically created by WAD but manually created by the developers.
- AD_MENU: It represents the menu entries displayed into the Application Menu
- AD_MESSAGE: It mainly contains all the messages the application displays, like error or information messages. Apart from messages, developers include also here the labels for manually generated windows created since Openbravo 3.
- AD_PROCESS: The name, description and help of the processes or reports available in the ERP are stored here.
- AD_PROCESS_PARA: It contains parameters related to processes
- AD_REFERENCE: It includes the definition of references, which are usually used to define new data types or list of values. See http://wiki.openbravo.com/wiki/ERP/2.50/Developers_Guide/Concepts/AD/Data_Model#References for more info about references.
- AD_REF_LIST: It stores the values for the references of the list type.
- AD_TAB: It contains the name, description and help for all the tabs in the application.
- AD_TEXTINTERFACES: It holds the texts that will be displayed in all the manually generated windows and reports. See http://wiki.openbravo.com/wiki/ERP_2.50:Developers_Guide/Concepts/Multi-Language_and_Translations#Manual_UI for more info.
- AD_WINDOW: It has the names, descriptions and helps of the WAD generated windows.
- OBCQL_QUERY_COLUMN: Related to the Query/List Widget module. It contains column information of widgets.
- OBKMO_WIDGET_CLASS_MENU: Related to the Workspace & Widgets module. It contains the widget's menu entries
- OBKMO_WIDGET_CLASS: Related to the Workspace & Widgets module. It contains the widget's title and description.
- OBUIAPP_PARAMETER: Related to the User Interface Application module. It contains the parameters related to Widgets and the new Process Definition.
- OBUISEL_SELECTOR_FIELD: Related to the User Interface Selector module. It contains the columns which are shown in the suggestion box and in the popup grid of the new selectors based on Smartclient.
- OBUISEL_SELECTOR: Related to the User Interface Selector module. It defines the name, description and help for the new selectors.
The previous list corresponds to the translation tables included into the Openbravo 3 distribution. Take into account that any module can extend the list of tables to be translated. In this case the export translation process will automatically create the new necessary XML files to be translated.
Populating translation tables
When the user installs a translation module, the ERP reads the translation XML files inside the referencedata/translation/<language ISO code>_<country ISO code> and imports all the translated strings to its corresponding _TRL table of the database. In case of using the Import translation process, the XML are read from the attachments/lang/<language ISO code>_<country ISO code>/<java package name> folder of your instance. Both ways can be used for importing translations.
Inside the Application Dictionary, the user can afterward check the imported translation at its respective table, having the possibility to even modify the translated strings and to export the updated XML files again through the Export translation process.
For example, imagine we have forgotten to translate a concrete message. As System Administrator role, we can open the Message window and search for the original message. Inside the Translation tab, which is associated with the AD_MESSAGE_TRL table, we will find the translation for this message. We can safely modify it and export the translation again.