Translating Openbravo

source: http://wiki.openbravo.com/wiki/Translating_Openbravo#Installing_a_new_translation

1 Introduction 2 Creating a language 3 Language pack 3.1 Structure 3.2 Translating using PO files 3.2.1 Software required 3.2.2 Generating a PO from an XML file 3.2.3 Translating PO files 3.2.4 Generating an XML from a PO file 3.3 Export/Import 3.4 Maintaining a translation 4 Installing a new translation

Introduction

This document explains the process of translating and maintaining Openbravo ERP translations 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

To translate Openbravo ERP, first create a language or activate a previously defined language.
Log in to Openbravo ERP using the System Administrator role.
Next, go to General Setup > Application > Language.

Here the language of choice can be selected from the list.
If you are not in Grid View, click the grid icon or create it. If you are creating a new language follow the Java convention of country and language:
The language with 2 lower case letters followed by an underscore (_) and the country in 2 capital letters (e.g. fr_CA stands for Canadian French).
Check the System Language check-box and save the record. This 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 (2.4x and onwards), which is requested during the installation process and, by default, is called /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_TRL_es_ES.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 is called lg_CT, where lg stands for language and CT for country, is:

1. AD_ALERTRULE_TRL_lg_CT.xml: Translations for AD_AlertRule table.
2. 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.
3. AD_FIELDGROUP_TRL_lg_CT.xml: Translations for AD_FieldGroup table. Field groups are used to group a fields in a window.
4. 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.
5. 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.
6. 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.
7. AD_MESSAGE_TRL_lg_CT.xml: Translations for AD_Message table. This table defines all the messages that application displays.
8. AD_PROCESS_PARA_TRL_lg_CT.xml: Translations for the AD_Process_Para table.
9. 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.
10. 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.
11. AD_REF_LIST_TRL_lg_CT.xml: Translations for AD_Ref_List table. In this table are found the values for the references of list type.
12. 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.
13. AD_TASK_TRL_lg_CT.xml: Translations for AD_Task table. Definition of system tasks.
14. 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.
15. AD_WF_NODE_TRL_lg_CT.xml: Translations for AD_WF_Node table. This table contains the workflow nodes.
16. AD_WINDOW_TRL_lg_CT.xml: Translations for AD_Window table. AD_Window has names, descriptions and helps of the WAD generated windows.
17. AD_WORKFLOW_TRL_lg_CT.xml: Translations for AD_Workflow table. Name, description and help for the defined workflows.
18. AT_COMMAND_TRL_lg_CT.xml: Translations for AT_Command table. This table is not used at this moment.
19. C_COUNTRY_TRL_lg_CT.xml: Translations for C_Country table. This table holds a list of countries.
20. C_CURRENCY_TRL_lg_CT.xml: Translations for C_Currency table. This table holds a list of currencies.
21. C_DOCTYPE_TRL_lg_CT.xml: Translations for C_DocType table. Description of the document types.
22. C_ELEMENTVALUE_TRL_lg_CT.xml: Translations for C_ElementValue table. This table contains the values for the elements used in accounting.
23. C_GREETING_TRL_lg_CT.xml: Translations for C_Greeting table.
24. C_PAYMENTTERM_TRL_lg_CT.xml: Translations for C_PaymentTerm table. Name and description for payment terms.
25. C_TAXCATEGORY_TRL_lg_CT.xml: Translations for C_TaxCategory table. Name and description for the tax categories.
26. C_TAX_TRL_lg_CT.xml: Translations for C_Tax table. Name and description for taxes.
27. C_UOM_TRL_lg_CT.xml: Translations for C_UOM table. This table contains the Units of Measure.
28. M_PRODUCT_TRL_lg_CT.xml: Translations for M_Product table. A table containing the different products.

* Note: The recommended way of translating is to translate the AD_ELEMENT table first. Then import the translated file, perform a Synchronize Terminology process, export again and continue. This is recommended because the AD_FIELD elements that are centrally maintained (most part of them) are updated with the AD_ELEMENT values every time this process is run. So a lot of effort and time is saved!

Note: Starting 2.50 MP19, you will find an additional file here: buildStructure.xml. This file contains the information related to the names different stages an Openbravo build goes through, and the error and warning messages that can be shown during a rebuild. You should also translate this file. Its information will be shown in the Rebuild Window, during a system rebuild (for example, when you install a module, or when you update Openbravo) This file follows a special format and will not work with the Openbravo2PO utility. However, as it is very small and easy to understand, it is very easy to directly translate it

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, these XML files can be converted into PO files, that are more user friendly.
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:

• Openbravo2PO which is a tool written specifically for working with Openbravo ERP generated XML files. It transforms XML format files to PO format and back to XML format. Openbravo2PO can also be used to merge multiple PO files of the same type (table, element, language) to a single file.
• Java version 1.5
• Ant version 1.7.0

Generating a PO from an XML file

Language files are exported from Openbravo ERP in XML format. In order to translate these files efficiently it is necessary to transform them into PO format files.
Detailed instructions on using this tool can be found at Openbravo2PO User Documentation
To transform XML files to PO format use the following ant command:

ant runXML2PO -DinpFold= -DoutFold= -DmsgStr= -Dfile=""

Add values as required to the various target arguments. If the -DinpFold is given and the -Dfile is empty the tool will generate PO files for all XML files in the input folder, otherwise only those files included in the -Dfile argument will be transformed. The -Dfile argument can take multiple files separated by a space character but must be enclosed in "".
E.g. to transform all XML files in a folder to PO files:

ant runXML2PO -DinpFold=/home/openbravo/translations/xml_base/ -DoutFold=/home/openbravo/translations/po_out/ -DmsgStr=false

E.g. to transform a single XML file:

ant runXML2PO -DinpFold=/home/openbravo/translations/xml_base/ -DoutFold=/home/openbravo/translations/po_out/ -DmsgStr=false -Dfile="AD_TASK_TRL_es_ES.xml"

Translating PO files

To translate a PO file 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.
• Lokalize – a graphical PO editor for the KDE environment (previously known as Kbabel).
• 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 XML format.
Detailed instructions on using this tool can be found at Openbravo2PO User Documentation
To generate the XML files from the PO files use the following ant target:

ant runPO2XML -DinpFold= -DoutFold=  -Dfile=""

Again, specifying the -DinpFold and not the file names will parse all PO files into the relevant XML files ready to be imported back into Openbravo ERP. The -Dfile argument can take multiple files separated by a space character but must be enclosed in "".
E.g. to process a complete folder:

ant runPO2XML -DinpFold=/home/openbravo/translations/po_out/ -DoutFold=/home/openbravo/translations/xml_trl

E.g. to process specific file(s):

ant runPO2XML -DinpFold=/home/openbravo/translations/po_out/ -DoutFold=/home/openbravo/translations/xml_trl -Dfile="AD_TASK_Name_es_ES.po AD_TASK_Help_es_ES.po AD_TASK_Description_es_ES.po"

Export/Import

To export or import a language, you 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).
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 and onwards).
• 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 you do not want to make a complete translation or significant changes, you 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 a tab called Translation in its window. Here, translations can be edited for each row of the table.
For example, if you simply want to change the Spanish translation for AccountType element, this change can be made by going to the Application Dictionary > Setup > Element > Translation tab.

Installing a new translation

Important The section that follows is the only way to install a translation for Openbravo ERP 2.40 an prior versions, or Openbravo ERP 2.50 if the translation module hasn't been already built (as described in this instructions). If the translation module exists, just go to General Setup > Application > Module Management > Add Modules, and install the translation module. After building the system, translation will be correctly translated.

To install a new translation in Openbravo ERP follow these steps:

• Click the Openbravo - Profile Button at the top menu, choose the role System Administrator and click the OK Button.

• Go to the General Setup > Application > Language menu option and search for the language that you want to import, e.g. Ger for Germany

• Mark the System Language check box then Save the record (it has a disk as an image). Do not check the Base Language check box.

• Click on the Verify Languages button to create the records for the language (if you already performed this action, result of the process should be 0, otherwise, the amount of new records created will be shown).

• An easy way to confirm that the process run correctly, is to check that new lines have been created in the translation tab of the windows. For example:
  • Go to Application Dictionary > Setup > Element.
  • Go to Translation tab.
  • Verify that a new line has been created for the language chosen. The contents of the tab should be in English. The real translation will take place in the following steps. If there is no new line, make sure you have saved the record after checking System language check box, and press Verify language again.

• Now, create in the Openbravo ERP directory (where you installed Openbravo ERP), a folder named AppsOpenbravo/attachments/lang/de_DE (for German Germany, in any other case, lg_CT corresponding to your language_COUNTRY).

• After that, download the translated XML files (in ZIP format) for your country. Unzip and copy them to AppsOpenbravo/attachments/lang/lg_CT folder.

• Go to General Setup > Application > Import/Export Translations menu. Select the language that you want to import in Language combo box. If you do not see the language that you want to import:
  • Go back to General Setup > Application > Language.
  • Select the language that you want to import, mark System Language check box then Save the record.
  • Click the Verify Languages button to create the records for the language (if you already performed this action, the result of the process should be 0).

• Click the Import button to start the import of the translation. An easy way to confirm that the process runs correctly is to check that the lines in the translation tab of the windows have been translated. For example:
  • Go to Application Dictionary > Setup > Element.
  • Go to Translation tab.
  • Verify that the record is displayed with the content translated to the choosen language. If results keep displaying in English, press the Import button again.

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

The recompilation is only required for 2.40 or earlier release

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

service tomcat stop

• Once it has stopped, start the Openbravo compilation by process by typing:

ant compile.complete

Important note: if you find this error compileSqlc: BUILD FAILED ...AppsOpenbravo/build.xml:85: The following error occurred while executing this line: ...AppsOpenbravo/src/build.xml:176: srcdir "...AppsOpenbravo/build/javasqlc/srcAD/org/openbravo/er pCommon/reference" does not exist! try to run: ant core.lib wad.lib trl.lib If success, run again: ant compile.complete

This process compiles and translates every window in the application.

• Now, create the openbravo.war file and deploy it to Apache Tomcat by typing:

ant war
ant deploy

* Choose

• Restart the web server by typing:

service tomcat start

Important note: at this point, you should have inside Apache Tomcat webapps folder (C:\Apache Software Foundation\Tomcat5.5\webapps\ or C:\Tomcat5.5\webapps\ in Microsoft Windows and /var/lib/tomcat5.5/webapps/ in Linux): A your_context_name folder (e.g., openbravo). A src-loc/design sub-folder with the english_USA version of Openbravo ERP. A src-loc/lg_CT sub-folder with your language_COUNTRY version of Openbravo ERP (e.g., src-loc/de_DE for Germany, src-loc/es_ES for Spanish of Spain, etc...). If this is not the case: service tomcat stop ant compile.complete ant war ant deploy service tomcat start Sometimes when you have yet deployed openbravo application to the Apache Tomcat webapps folder, you could continue experiencing problems. Try: service tomcat stop delete your_context_name folder (e.g., openbravo) inside Apache Tomcat webapps folder. service tomcat start your_context_name folder should be re-created with the src-loc/lg_CT subfolders inside it.

• Now login into Openbravo ERP and you will be able set your language for your Role. If you want to see all the menus in your language, mark the check-box Set as Default.