Translating Openbravo

Introduction

This document explains the process of translating and maintaining translations of Openbravo ERP into different languages.

The process involves five steps:

1. Creating a new language.
2. Copying the base language translations.
3. Exporting the XML files to translate.
4. Translating the files.
5. Finally, importing the new translations into the system.

Creating a Language

In order to translate Openbravo ERP, the first step is to create a language or to activate a previously defined language. Indeed, there are many languages listed so it is likely that the user only needs to activate one of them to translate.

The user must sign in to Openbravo ERP using the System Administrator role. Next, go to General Setup > Application > Language.

Here the language of choice may be selected from the list (if the user is not in Grid View, he or she should click the grid icon) or create it. If a new language is going to be created it should follow the Java convention of country and language: the language with 2 lower letters followed by an underscore (_) and the country as 2 capital letters (e.g. fr_CN would stand for Canadian French). By checking the System Language check-box and saving the record, the user activates the language to translate and from this point, it appears in the user's preferences.

The next step is to copy all text from the Base Language to the new language. The base language is the language that is used as a starting point for translating the application, and it is English (en_US). By clicking on Verify Languages button all the strings for the base language are copied to the new language.

Language Pack

Structure

A language pack is a set of XML files containing the translations for a desired language. Each file contains the translation for a single table in the database and is given the same name as the table which contains its corresponding translation.

These language packs are stored in a server directory by language using the convention of language and country (e.g. en_US, es_ES...). They are inside a lang directory in the folder that is defined to contain all attachments. This is defined in your local build.xml file (for 2.3x versions) or Openbravo.properties file (for 2.4x versions), is requested during the installation process and, by default, is /attachments. An example of a complete path for Spanish_Spain could be /attachments/lang/es_ES.

The structure of the XML is as follows:

• A tag 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 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 and original signifying the value for the column in the base language (English). 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 /attachments/lang/es_ES/AD_TASK.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<compiereTrl language="es_ES" table="AD_TASK">
  <row id="102" trl="Y">
    <value column="Name" original="Java Version">Versión de java</value>
    <value column="Description" original="Displays the version of the default Java VM">Muestra la versión de la java VM por defecto</value>
    <value column="Help" original="The java version used by the application might be different."/>
  </row>
  <row id="103" trl="N">
    <value column="Name" original="Database Export">Exportar BD</value>
    <value column="Description" original="Export (save) the database">Exportar (guardar) la base de datos</value>
    <value column="Help" original="Run this command from the server">Run this command from the server</value>
  </row>
</compiereTrl>

The complete list of XML files that compose a language pack called lg_CT, where lg stands for language and CT for country, is:

• AD_DESKTOP_TRL_lg_CT.xml: Translations for AD_Desktop. This table is not used at this moment.
• AD_ELEMENT_TRL_lg_CT.xml: Translations for the AD_Element table. This table contains all the elements of the application. They are used in order to have centrally maintained a description and help of the elements.
• AD_FIELDGROUP_TRL_lg_CT.xml: Translations for AD_FieldGroup. Field groups are used to group a fields in a window.
• AD_FIELD_TRL_lg_CT.xml: Translations for the AD_Field table. This table holds the information about the fields that are shown in each window of the application.
• AD_FORM_TRL_lg_CT.xml: Translations for the AD_Form table, where are defined the name, description and help for all the forms of the application. A form is a manually generated window.
• AD_MENU_TRL_lg_CT.xml: Translations for AD_Menu table. Here can be found the menu tree that appears on the left side of the application.
• AD_MESSAGE_TRL_lg_CT.xml: Translations for AD_Message table. This table defines all the messages that application displays.
• AD_PRINTFORMATITEM_TRL_lg_CT.xml: Translations for AD_PrintFormatCTEM. This table is not used at this moment.
• AD_PRINTLABELLINE_TRL_lg_CT.xml: Translations for AD_PrintLabelLine. This table is not used at this moment.
• AD_PROCESS_PARA_TRL_lg_CT.xml: Translations for the AD_Process_Para table.
• AD_PROCESS_TRL_lg_CT.xml: Translations for AD_Process table. Here appears the name, description and help for the processes invoked from the application.
• AD_REFERENCE_TRL_lg_CT.xml: Translations for AD_Reference table. In this table are all the references. References are used to define data types, lists of values or tables.
• AD_REF_LIST_TRL_lg_CT.xml: Translations for AD_Ref_List. In this table are found the values for the references of list type.
• AD_TAB_TRL_lg_CT.xml: Translations for AD_Tab table. This table contains the name, description and help for all the tabs in the application.
• AD_TASK_TRL_lg_CT.xml: Translations for AD_Task. Definition of system tasks.
• AD_TEXTINTERFACES_TRL_lg_CT.xml: Translations for AD_TextInterfaces table. This table holds the texts that will be displayed in all the manually generated windows.
• AD_WF_NODE_TRL_lg_CT.xml: Translations for AD_WF_Node. This table contains the workflow nodes.
• AD_WINDOW_TRL_lg_CT.xml: Translations for AD_Window table. AD_Window has names, descriptions and helps of the WAD generated windows.
• AD_WORKBENCH_TRL_lg_CT.xml: Translations for AD_Workbench. This table is not used at this moment.
• AD_WORKFLOW_TRL_lg_CT.xml: Translations for AD_Workflow. Name, description and help for the defined workflows.
• C_COUNTRY_TRL_lg_CT.xml: Translations for C_Country. This table holds a list of countries.
• C_DOCTYPE_TRL_lg_CT.xml: Translations for C_DocType. Description of the document types.
• C_DUNNINGLEVEL_TRL_lg_CT.xml: Translations for C_DunningLevel. This table is not used at this moment.
• C_ELEMENTVALUE_TRL_lg_CT.xml: Translations for C_PaymentValue table. This table contains the values for the elements used in accounting.
• C_GREETING_TRL_lg_CT.xml: Translations for C_Greeting.
• C_PAYMENTTERM_TRL_lg_CT.xml: Translations for C_PaymentTerm. Name and description for payment terms.
• C_TAXCATEGORY_TRL_lg_CT.xml: Translations for C_TaxCategory table. Name and description for the tax categories.
• C_TAX_TRL_lg_CT.xml: Translations for C_Tax table. Name and description for taxes.
• C_UOM_TRL_lg_CT.xml: Translations for C_OUM table. This table contains the Units of Measure.
• M_PRODUCT_TRL_lg_CT.xml: Translations for M_Product table. A table containing the different products.

Translating using PO files

PO (Portable Object) is a very popular format for storing and translating many open source applications. Openbravo ERP uses XML to import and export translations. However, with little effort, these XML files can be converted into PO files, that are more easy and friendly to work with.

PO files have a very simple structure. They look like:

#: AD_MENU_TRL_en_US.xml:1(value) 
msgid "original text"
msgstr "translated text"

There is detailed description of the format in the GNU gettext utilities manual.

Software required

To translate Openbravo using PO files, the following software is required:

• GNU Gettext provides the standard tools for managing PO files.
• xml2po is a simple Python program which extracts translatable content from free-form XML documents and outputs gettext compatible POT files. Translated PO files can be turned into XML output again. It is packaged for many Linux distributions.

Additionally, if you want to do a batch process for all the files you can use the helper scripts provided by Openbravo available from SourceForge.

Generating a PO from a XML file

To generate a PO from an XML source using xml2po just type:

xml2po file.xml > file.po

and the corresponding PO for the given XML is generated.

Translating PO files

To translate a PO into your language you can use one of the many open source tools and editors available. Some of the most popular are:

• PoEdit. A cross-platform gettext catalogs editor.
• KBabel. A graphical PO editor for the KDE environment.
• Gtranslator. A graphical PO editor for the GNOME environment.

Generating an XML from a PO file

Once the translation is complete you have to put the translations back into the XML files. To generate an XML from a PO file using xml2po just type:

po2xml -p file.po reference_xml_file.xml > output.xml

and the corresponding XML holding the translations generated.

Automating the process

It is also possible to automate the process of generating PO files and exporting them back to XML files using the helper scripts.

Create a directory structure to hold the source and translated files. The following directory structure is recommended:

localization
  |-src_xml
  |-po
  |-out_xml

• localization: Where the scripts are stored and executed from.
• src_xml: Where the XML source files exported from Openbravo are stored.
• po: Where the PO files generated from the source files are stored.
• out_xml: Where the final translated XML files are stored.

Copy the XmlToPo.sh and PoToXml.sh helper scripts to the root directory (localization).

Use XmlToPo.sh to convert all XML into PO files. After translating the files, use the PoToXml.sh script to convert back the PO files into XML.

Export/Import

To export or import a language the user must log into the application as System Administrator and go to General Setup > Application > Import/Export Translations ( the language must be activated in the system first).

Here the user can choose one of the languages defined as System Language.

• Export: Creates the language directory (see above) if it does not already exist and exports the files for the selected language to the directory.
• Import: Reads the files from the selected language directory and import them into the application database tables.

The desired language XML files are located in the following directory: attachments/lang/en_US

• The location of the attachments folder is configured in the attach.path property in your local build.xml file (for 2.3x versions) or Openbravo.properties file (for 2.4x versions).
• en_US should be replaced with the code for your particular language.

See the Installing a new translation section if you are importing translations.

Maintaining a Translation

If the user does not want to make a complete translation nor significant changes, he or she can modify a translation in a different way, without exporting/modifying/importing XML files. Every table that has a translation (the ones that are exported into XML files), also has in its window a tab called Translation. Here, translations can be edited for each row of the table. For example, if the user simply wants to change the Spanish translation for AccountType element, this change is made by going to the Application Dictionary > Setup > Element > Translation tab. Once there, changes can be made.

Installing a new translation

To install a new translation in Openbravo follow these steps:

1. Login as system administrator in the application.
2. Go to the General Setup > Application > Language menu option and select the language that you want to import.
3. Mark the System Language check box for the language and then use the Save Record (it has a disk as an image) icon to save the changes. Do not check the Base Language checkbox.
4. Press the Verify Languages button to create the records for the language.
5. Place the translated XML files inside the lang directory in the folder that is defined to contain all attachments. This is defined at web.xml file, is requested during the installation process, and by default is AppsOpenbravo/attach. An example of a complete path for Spanish/Spain could be AppsOpenbravo/attach/lang/es_ES.
6. Go to the General Setup->Application->Import/Export translation menu. Select the in the language combo box the name of the language that you want to import and press the Import button.

Once the translations are imported or changes have been made, the modifications do not take effect until Openbravo is recompiled and a new openbravo.war is deployed.

It is recommended to stop the web server before stating the compiling process. For example: if using Tomcat as web server in a Linux, shut it down by typing the command:

service tomcat stop

Once is stopped, start the Openbravo compilation by process by typing:

ant compile.complete

This process compiles and translates every window in the application. Now, create the openbravo.war file by typing:

ant war
ant deploy

Restart the web server by typing:

service tomcat start

Login into Openbravo, click on the user's preferences and select the language that you want to use.