Projects:Translation PO Merge/User Documentation
Contents |
Openbravo2PO Tool - User Documentation
Openbravo2PO is a utility providing file transformation functionality for Openbravo translation projects.
Version 2 of Openbravo2PO is based on the original contribution from Jens Wilke.
If you find any issues with this tool or have feature requests on further development then please raise these through the Openbravo Issues management site. You will find Openbravo2PO under the tools project.
Installing/Building/Testing
This application can be built and run through the ANT build commands, either in the command line or with the Eclipse IDE. The main targets within the ANT build file are:
- Jar: compiles and jars the application.
- Test: runs all unit tests within the tests/src folder of the distribution.
- Run: runs the specified target with specified arguments.
Installation
The code can be obtained through the mercurial repository:
- Clone the mercurial repository with
hg clone https://code.openbravo.com/erp/mods/org.openbravo.xmlpo
- Configure the logging output folder. Refer to the section below on Logging.
- Verify the application compiles and builds using:
ant jar
- Verify all tests pass correctly using:
ant test
To run this you may need to copy the ant-junit.jar in the lib folder to you ANT_HOME/lib folder.
Logging
A log configuration file is provided and this will output useful information to the Openbravo2PO top level folder. This destination can be changed in the log4j.properties file located in the src folder.
Edit the line:
log4j.appender.R.File=log4j_OB2PO.log
The level of debugging is set in the row:
log4j.rootCategory=INFO, R
Unit Testing
Unit tests are included which validate the construct of each object and the relevant files output by the application. These can be run using:
ant test
Either in command line or executing specific tests within the eclipse IDE.
The source code for these tests is located in the tests/src folder and results will be output in html format for viewing in a browser by opening the
openbravo2po/docs/reports/index.html file.
Execution
There are three main functions - XML2PO, PO2XML, and POMerge.
Basic concepts
These are the basic functional requirements that this tool implements.
1. Multiple Rows/Same Strings: within an XML file there will often be repeated instances of the same msgid (Original text) and msgstr (Translation text) values. Where the tool finds these instances in the file it will consolidate them into a single PO file message object. During the parsing of the .po file back to an XML file, these multiple row instances will be broken back out into their individual row ids.
2. Merging and Consolidating repetition: for the purposes of this tool repetition is defined as matching msgid and msgstr values.
3. Merge Handling of Multiple Rows/Same Strings: during the process of running the merge, the application will break out the messages to individual rowids before matching with the second file. Once the merges have been identified they will be consolidated again provided they still have matching msgid and msgstr values, otherwise they will be listed as an individual row.
4. Version Consistency Handling: to provide consistency with the repository it has been necessary to make a slight change to the PO header information. This is a single line which helps define the sequencing of the value objects inside each row element in the XML file. The line"X-Openbravo-Index-Column: 3\n"will follow the column name in the file and will start at 1 incrementing by 1 for each element within the row. The first value element in the row will be 1.
<row id="104" trl="Y"> <value column="Name" original="104 Name">104 Name Value</value> <value column="Description" original="104 Description">104 Description Value</value> <value column="Help" original="104 Help">104 Help Value</value> </row>
will be shown as index 1 for the Name po file, index 2 for the Description po file, and index 3 for the Help po file.
"X-Openbravo-Table: AD_TASK\n" "X-Openbravo-Column: Help\n" "X-Openbravo-Index-Column: 3\n"
This index column is automatically generated using the application although it may be necessary to manually include this in older po files generated from openbravo2po version 1.0.
5. XML File Element Padding: When an XML file is generated each row will be padded with all the required value elements even if there is no column element for that row. In this instance the column will be generated with an Original and Translation value of ""
<row id="103" trl="Y"> <value column="Name" original="103 Name">103 Name Value</value> <value column="Description" original="103 Description">103 Description Value</value> <value column="Help" original=""></value> </row>
XML2PO
Overview
The XML2PO function takes XML files exported by the Openbravo application and transforms them into files that can be edited in a PO editing/translation tool. During the transformation process a separate file is created for each column within the XML file, e.g. AD_TASK_Name_it_IT.po.
The options available to the user for running this command are:
- InputFolder - [-DinpFold] - Optional: this defines the source folder from where the application will get the files to transform. If the file option is not used, then the application will assume that all files will be transformed. If the file option is used and this option is not null, then the final file path will be a concatenation of both the input folder path and the file name.
- OutputFolder - [-DoutFold] - Optional: this option defines the folder where the transformed files will be output to. If this option is not specified then the output path will be the same folder as the folder from where the input file was obtained.
- MessageString - [-DmsgStr] - Optional (defaults to False): use this option if you want the output of the PO file to show an empty msgstr if the value text is the same as the original text in the XML document. Essentially this means that there is no translation for this field and that one needs to be created. Valid values for this argument are yes or no.
- File - [-Dfile=""] - Optional: enter a space separated listing of files for the application to transform. If the input folder option is also specified then the full file path will consist of the input folder string plus the file name.
Command
ant runXML2PO -DinpFold= -DoutFold= -DmsgStr= -Dfile=""
e.g. ant runXML2PO -DinpFold=/openbravo/attachment/lang/en_US/ -DoutFold=/home/tmp -DmsgStr=yes =Dfile="AD_TASK_TRL_en_US.xml"
PO2XML
Overview
This function will take files of a .po nature and transform them to a .xml file suitable for importing into Openbravo through the language import menu item. If a list of files or an input folder is passed as an argument then the application will iterate through the files and generate a single XML file for each table/language combination. If the value and original text are the same or the value entry is empty then the trl flag in the Row element will be set to 'N', this identifies that there is no translation for this original value.
- InputFolder - [-DinpFold] - Optional: this defines the source folder from where the application will get the files to transform. If the file option is not used then the application will assume that all files will be transformed. If the file option is used and this option is not null, then the final file path will be a concatenation of both the input folder path and the file name.
- OutputFolder - [-DoutFold] - Optional: this option defines the folder where the transformed files will be output to. If this option is not specified then the output path will be the same folder as the folder from where the input file was obtained.
- File - [-Dfile=""] - Optional: enter a space separated listing of files for the application to transform. If the input folder option is also specified then the full file path will consist of the input folder string plus the file name.
Command
ant runPO2XML -DinpFold= -DoutFold= -Dfile=""
POMerge
Overview
The merge function allows the user to merge multiple .po files into a single file. During the process of merging that application will validate that the table, language, and column for the PO files are the same. If they are not then an error will be returned. The action here is to take unique rowId entries from each file and merge them to a single file. For those entries where there is a rowId conflict then the actions are:
- Check that the msgid values are not the same.
- Check that the msgstr values are different.
If the msgid and msgstr values are different, then the record will be identified as a duplicate and the string '# DUPLICATION' will be added to the comment section of the merged message. If the values are the same then the record will be treated as a duplicate rather than a conflict and a clean single entry will be created. This entry will not be marked as a duplicate. Further useful information can be found in the logging file which will summarise the duplicated lines within each file. When the file is saved to a location it will be saved with _MERGED.po as the filename ending.
- OutputFolder - [-DoutFold] - Optional: this option defines the folder where the transformed files will be output to. If this option is not specified then the output path will be the same folder as the folder from where the input file was obtained.
- File - [-Dfile=""] - Optional: enter a space separated listing of files for the application to transform.
Command
ant runPOMerge -DoutFold= -Dfile="" # for example: ant runPOMerge -DoutFold=/home/tmp -Dfile="/home/folder1/AD_TASK_Name_en_US.po /home/folder2/AD_TASK_Name_en_US.po"