Category:Localization Process
Languages: |
English | Translate this article... |
Introduction
Localizations are very important for Openbravo ERP project and our community is doing a great effort creating and maintaining them and giving suggestions to enhance Openbravo ERP product to better suite the needs of different regions around the world.
This document describes the localization process for Openbravo ERP. It involves several collaboration tools and people and it's very important that you follow it carefully.
Basic localization process
- Check in the Current localization projects wiki page that there is no effort for your country or region. If there is an on-going effort, write the person listed as a contact and try to collaborate with her. If the person is not answering to your mails, send a message to the message thread for that effort explaining the situation and request to lead a new effort.
- If you are leading a new effort, you should follow these steps:
- Notify the localization coordinator at Openbravo of your effort sending an e-mail to Richard Morley <richard.morley AT openbravo.com>. Indicate also your schedule for your localization effort.
- A message thread for the localization effort should be created at the Localization forum.
- It is very important as a leader for an effort that you monitor the traffic for the message thread created for your effort. You can do so using the Monitor this forum option in the SourceForge forums. Note that the forums have been moved to Openbravo Forge.
- Send the details of your effort (indicating the address of the project forum to coordinate and your contact details) to Richard Morley <richard.morley AT openbravo.com>. He will register your effort in projects section of Current localization projects wiki page.
- The translations and chart of accounts are stored in the Openbravo Subversion Server. There is a page explaining how to use Subversion and you can also browse the translations and accounting directories. You should request an SVN account to Richard Morley <richard.morley AT openbravo.com> to be able to publish your work in our Subversion server. It is important to follow the repository structure in Subversion directories.
- Start the localization process.
- We request the localizers to upload their work to Subversion every two weeks in a pure open source approach, then people can follow your progress and give feedback to you.
- If you have any doubt or question, publish it in the forum created for your localization effort. Openbravo users and developers monitor that forum on a daily basis.
- If you think that your region has a functional or localization requirement that is not covered by Openbravo ERP, register it in our Localization Special Requirements page where we keep track of all of these.
- A translation is considered complete when all the user interface is translated. A chart of accounts should pass test1 and test2 to be published. We also strongly recommend to pass also test 3.
- Once your work is considered complete, a beta version can be published. Contact Richard Morley <richard.morley AT openbravo.com> to start this process. The process includes:
- Package the localization and make it available at Openbravo Forge where you can register a localization project.
- Prepare a note to announce it on the Openbravo Forge. See an example.
- Announce it in the localization forum.
- Keep the new versions of Openbravo up to date and repeat the process again.
Complete localization
- You should start by analyzing the most successful local solutions in your market. For example, for the US localization, a local solution such as Quickbook should be analyzed.
- Based on this analysis, you should define a list of localization gaps, which are features that need to be implemented in Openbravo in order to be competitive with that local solution. Please notice that you should focus on local capabilities only for this analysis and not on additional geography independent functionality; this is to a large degree a subjective assessment but it is important that your localization efforts do not get sidetracked by other potential functional gaps.
- Contact Openbravo localization team: collaborate AT openbravo.com
- Collaborate: join efforts from country community members.
- A message thread for the localization effort should be created at the Localization forum.
- It is very important as a leader for an effort that your monitor the traffic for the message thread created for your effort. You can do so using the Monitor this forum option in the SourceForge forums.
- Openbravo team will create a branch in our subversion repository for the project following the naming conventions and will give you the rights to develop there.
- Get a developer ID. Note: this is not needed starting with r2.50.
- Get rights to access the new branch (user and password)
- Write a functional and technical documentation for the project.
- Do continuous merges from trunk to your branch to keep updated and avoid future problems.
- Packaging:
- OB 2.40: Country OB version can be created from the branch.
- OB 2.50: A module for the specific country can be created from the branch.
Any particular development that makes sense to be included as part of the product core can be developed separately and contributed to the core. This means not taking care of that code any more. Openbravo team will help you doing the functional and technical specification but also will take care of that piece of code for future versions compatibility. See contributor guide.
Localization modules
The modularity features of Openbravo ERP 2.50 onwards enable localizers to create a discrete extension module which can be easily developed and shared with other users via the Openbravo central repository. It is strongly recommended that you use a module for any localization effort.
There are many different types of localization module. This document particularly explains how to create translations, charts of accounts and standard reference data modules, since these modules have a specific registration process.
- Translations: Translation modules cannot include any content apart from the translation. For example you cannot create a module that is both a translation and a chart of accounts, but you can create two separate modules and combine them as a pack. A translation module must translate from English into only one other language. For example you cannot use the same module for both French and German translations.
- Chart of accounts: The chart of accounts defines the appropriate accounting structure for a particular locale, to comply with approved local practice and law. The chart of accounts consists of a .csv file.
- Standard reference data: Standard reference data is data from the application tables, for example taxes and alerts. You can therefore export data from a table and convert it into a module that can be uploaded to the central repository or otherwise shared with other users.
You can also combine modules to create a localization pack.
In general, there are three stages to creating a module:
- Register: registering the module reserves a unique java package name for your module in the central repository.
- Develop: complete the development work using your preferred tools.
- Publish: publish the module to the central repository so that other users can access it.
To learn how to work with modules, consult the modularity developer's guide. Once you are confident with the concepts and techniques, use the guidelines that follow to specifically create localization modules.
Naming guidelines
For guidelines on naming modules please follow this link.
Java package naming conventions
Openbravo follows a Java package naming convention of: domain.contributor.module_name
Openbravo reserves the right to use org.openbravo as the domain and contributor designation, for example org.openbravo.initial_data_load.
Other organizations creating modules should use their own own organization name as the contributor designation when naming Java packages (unless there is a specific code contribution agreement in place that requires otherwise).
Examples of Java package names
The following table contains a description of recommended practices when naming Java packages:
Note:
langcode = ISO 639-1 language code
CTRYCODE = ISO 3166-1-alpha-2 country code
Module type | Explanation | Java Package Name Format | Java Package Name Example |
---|---|---|---|
Chart of Accounts where there is a standard chart for a country | Hungary has a standard chart of accounts. | domain.contributor.accounts(CTRYCODE) | com.mycompany.accounts(HU) |
Chart of Accounts where there is more than one chart per country | In Spain small companies use a chart of accounts called PGC 2007 PYMEs, while larger companies use a different chart. | domain.contributor.accounts.accounts_name(CTRYCODE) | com.mycompany.accounts.pgc_2007_pyme(ES) |
Translation of Core | The translation of core Openbravo into Arabic for Saudi Arabia | domain.contributor.translation(langcode_CTRYCODE) | com.mycompany.translation(ar_SA) |
Translation of Module | The translation of the Tax Report Launcher module into Spanish. | domain.contributor.translation.module_name(langcode_CTRYCODE) | com.mycompany.translation.tax_report_launcher(es_ES) |
Tax configuration module | Configuration of taxes for a particular country | domain.contributor.tax_configuration(CTRYCODE) | com.mycompany.tax_configuration(FR) |
Tax report module | A tax report for a particular country, e.g., Spain has a tax report called Modelo 347 which is delivered as a module | domain.contributor.tax_report.report_name(CTRYCODE) | com.mycompany.tax_report.modelo_347(ES) |
Region modules | A module that delivers names of regions (counties, states, regions) within a country, for example the regions of Brazil. | domain.contributor.regions(CTRYCODE) | com.mycompany.regions(BR) |
Report modules (other than tax reports) | A generic report in a particular language that can be used everywhere, for example a “Shipments Awaiting Invoice” report in English. | domain.contributor.report.report_name(langcode) | com.mycompany.report.shipments_awaiting_invoice(en) |
Skin | You like blue.... | domain.contributor.skin.skin_name | com.mycompany.skin.blue_sea |
Tutorial | Modules developed purely as examples to illustrate how to develop modules | domain.contributor.tutorial.tutorial_name | com.mycompany.tutorial.solitaire |
Creating a translation module
For detailed guidance on translating Openbravo ERP please visit the Translating Openbravo page.
Important The section that follows is the recommended way to install a translation for Openbravo ERP 2.50 onwards. The previous methodology as described in these instructions is still available as an option. |
To create a translation module follow the guidelines in the developer's guide and tutorials, but using the specific configuration described in this document. The process for creating a translation module is as follows:
- Register the translation module with the central repository.
- Export the database
- Obtain the xml files
- Translate the xml files
- Package the module
- Upload the module to the Openbravo Forge
Registering the translation module
When you register the module, fill in the fields as follows:
- From the Module Type list, select Module.
- In the Name field, type the java package name of the translation, using the correct naming convention.
- Fill the Version field. Start with 1.0.0 and keep increasing it when you improve it.
- Complete the Description and Help fields, using the language that you are translating into.
- Select the Is translation module option.
- Clear the Has reference data, Translation required and Has chart of accounts options.
- Select the In development option. Remember that you cannot work on a module unless the In development option is selected.
- Select the License Type.
- From the Module language menu, select the translation language. For example if you are translating into Czech, select Czech from the list.
- On the Dependencies tab, specify the module you are translating as the dependent module. For example if you are translating the Core module, select Core as the dependent module.
When you click Register Module you will be asked to supply your username and password for the Openbravo Forge. In the Forge, a module must be associated to a project.
Exporting the database
When you have registered the module, the next stage is to export the database to create the necessary module folders.
- Execute the command:
ant export.database
- Exporting the database creates a new subfolder within the Modules folder. The new folder has the same name as the java package of the translation module, for example modules/org.openbravo.mymodule.es_ES.
- Within the modules/org.openbravo.mymodule.xx_YY folder, manually create a subfolder called referencedata. You must use this exact name, note that it is all lower case and has no spaces.
- Within the referencedata folder, create another subfolder called translation.
- Within the 'translation folder create another folder for the translation, using the xx_YY language / country code naming convention. For example en_US for US English.
modules/org.openbravo.mymodule.xx_YY/referencedata/translation/xx_YY/
- Place the translated .xml files within the folder for its respective language.
Obtaining the .xml files
- Enter the ERP application as a System Administrator and go to General Setup > Application > Language menu option.
- Search for the language that you want to translate.
- Mark the System Language check box and Save the record (it has a disk as an image). Do not check the Base Language check box
- Press 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.
- Go to General Setup > Application > Import/Export Translations. Select the language and press Export.
- This step will create a folder hierarchy in the attachment folder you have defined (attach.path property) in your Openbravo.properties file. That folder hierarchy will be placed in a folder named lang. In that folder there will be at least two folders. One will be en_US (the default language Openbravo ERP comes with). And the second one will be the one you have exported (e.g. de_DE for German or es_ES for Spanish, see the previous table).
- Enter the folder of the language you have exported. You will be able to see an amount of .xml files and an amount of subfolders. The .xml files are the ones belonging to core. The subfolders you can see are the ones that contain the .xml files that belong to each module you have installed.
- Open the .xml files of the module you want to translate (not the files of the translation module).
- Note that there are many .xml files. The different objects to be translated are ordered in these files with a criteria. For further information follow the link at the beginning of the Creating a translation module section.
Translating the .xml files
You can now translate the .xml files using your preferred editor. Translate the text and change isTrl to Y in the ones you have translated. When you have finished translating, copy all the .xml files you have already translated from
attach.path/lang/xx_YY/org.openbravo.mymodule/*.xml
to the recently created module folder hierarchy
modules/org.openbravo.mymodule.xx_YY/referencedata/translation/xx_YY/
Packaging the module as an .obx file
To package the module, execute the command ant package.module -Dmodule=modulename, where modulename is the Java package name of the module.
Publishing the module to the Openbravo Forge
You are now ready to publish the module to the Openbravo forge
Translating core 3.0 version. Creating a translation pack
3.0 version of Openbravo
Since 3.0 version of Openbravo, the ERP is not just the core module, but a set of some other modules more. Because of that, in order to translate the ERP, it's necessary, not only to translate core module (as of now), but also to translate all the set of modules that makes the 3.0 version. So, the translation of 3.0 is not a translation module, but a set of translation modules. The best approach to manage this is to group all them together into one only pack.
Creating a Translation Pack
If a set of translation modules needs to be released as one only module (to avoid user having to install a lot of different modules), a pack can be created. If this pack includes all the set of translation modules that developer wants to install, when user installs the pack, all those modules will be installed.
Having into account the way dependencies are managed, there are some topics that developer must take into account when building a translation pack. Let's take, as an example, 3.0 RC3 version of ERP. This version is composed of the following modules and versions:
- Core - 3.0.9018
- Orders Awaiting Delivery - 1.0.2
- Standard Roles - 3.0.3
- Payment Report - 1.0.0
- Advanced Payables and Receivables Mngmt - 3.0.9
- JSON Datasource - 2.0.0
- JSON REST Webservice - 2.0.0
- My Openbravo Tab - 2.0.2
- User Interface Selector - 2.0.0
- Smartclient - 8.0.0
- 2.50 to 3.00 Compatibility Skin - 2.0.0
- Seam - 2.0.0
- User Interface Application - 2.0.1
- User Interface Client Kernel - 2.0.1
From these set of modules, only these ones do need to be translated:
- Core - 3.0.9018
- Orders Awaiting Delivery - 1.0.2
- Payment Report - 1.0.0
- Advanced Payables and Receivables Mngmt - 3.0.9
- JSON Datasource - 2.0.0
- My Openbravo Tab - 2.0.2
- User Interface Selector - 2.0.0
- Smartclient - 8.0.0
- User Interface Application - 2.0.1
- User Interface Client Kernel - 2.0.1
In a fresh clean instance of 3.0 RC3, the translation modules are installed, or created. The process of creating or updating the xml translation files is run. Once all the files are up to date, then a new package is created. This package will include all the translation modules. Then, the package is created through two easy ant tasks:
ant export.database ant package.module -Dmodule=java.package.name.of.the.pack
Important things to take into account
All the translation modules must be created in a exactly identical environment: same core version, and same translated modules versions. Otherwise, the pack may not install correctly. If all the translation process and packaging is executed in the same environment, all these problems will be avoided.
It's important, before exporting the database, to update the version of the module that is translated, in the dependencies tab. So, before exporting the database, go to the Module window, and for the record that corresponds to the translation pack, go to the Includes sub-tab. There, update the version of the included modules to the one actually installed in the system.
Tip: A fast way to do this is to go through all the entries in the Includes sub-tab,
change the selected module in the combo to whatever other one, and choose again the original one.
The call-out will fill-in the version field with the installed one.
Creating a chart of accounts module
The chart of accounts describes the accounting structure that Openbravo ERP uses. You can create a chart of accounts for a specific locale, for example to accomodate local accountancy practice or regulation. The chart of accounts consists of a .csv file that can be applied to a Client during the initial client setup process.
Before version 2.50, charts of accounts were downloaded from sourceforge and you can still use the Openbravo forge to upload and download charts of accounts. However, it is recommended that you create a module for charts of accounts and distribute it via the central repository because:
- The chart of accounts is visible to other users from the central repository, making it easier for users to apply and to check for updates.
- You can package the chart of accounts with other modules to create a complete localization solution.
Creating a chart of accounts module comprises the following steps:
- Register the chart of accounts module with the central repository.
- Create the folder structure to hold the chart of accounts file.
- Create the chart of accounts file and save it in the folder structure.
- Package the chart of accounts module.
- Publish the module to the Openbravo forge.
Registering a chart of accounts module
When you register the module, fill in the fields as follows:
- From the Module Type list, select Module.
- In the Name field, type the java package name of the translation, using the correct naming convention.
- Complete the Description and Help fields using natural language and supplying as much information about the chart of accounts as possible.
- Select the Has chart of accounts option.
- Clear the Has reference data, Translation required and Is translation module options.
- Select the In development option. Remember that you cannot work on a module unless the In development option is selected.
- On the Dependencies tab, select Core.
When you click Register Module you will be asked to supply your username and password for the Openbravo Forge.
Creating the chart of accounts file
Once you have registered the module, create the chart of accounts, using whichever package you prefer to create the .csv file.
Exporting the database
When you the chart of accounts file is ready, the next stage is to export the database to create the necessary module folders.
- Execute the command:
ant export.database
- Exporting the database creates a new subfolder within the Modules folder. The new folder has the same name as the java package of the translation module, for example modules/org.openbravo.referencedata.coa.ES_es.
- Within the Modules folder, manually create a subfolder called referencedata. You must use this exact name, note that it is all lower case and has no spaces.
- Within the referencedata folder, create another subfolder called accounts.
- Place the chart of accounts .csv file within the accounts folder.
Packaging the module as an .obx file
To package the module, execute the command ant package.module -Dmodule=modulename, where modulename is the Java package name of the module.
Publishing the module to the Openbravo Forge
You are now ready to publish the module to the Openbravo forge
Creating a standard reference data module
Standard reference data is data from Openbravo ERP's application tables, for example taxes and alerts. If you have set up Openbravo ERP in a particular way to meet local requirements, you can export this data and convert it to a module, so that you can share it with other users via the central repository.
The process for creating a standard reference data module is:
- Define and register the module in Openbravo ERP.
- Define and export the tables you require as a dataset.
- Package the module as an .obx file
- Create a project in the Openbravo Forge.
- Publish the module to the Openbravo Forge.
Registering a standard reference data module
- From the Module Type list, select Module.
- In the Name field, type the java package name of the module, using the correct naming convention.
- Complete the Description and Help fields using natural language and supplying as much information about the chart of accounts as possible.
- Select the Has reference data option.
- Clear the Has chart of accounts, Translation required and Is translation module options.
- Select the In development option. Remember that you cannot work on a module unless the In development option is selected.
- On the Dependencies tab, select Core.
Defining and exporting the dataset
- Log into Openbravo ERP
- From the Application menu, select Application Dictionary > Dataset
- Click New.
- From the Module list, select the module that will include the standard reference data.
- Specify a search key, name and description.
- From the Data Access Level list, select the Data access level from the following options:
- System only
- System/client
- Client/organization
- Organization
- Select the Export allowed option.
- Select the Table Tab
- From the Table list, select the table whose content you want to include in the module.
- In the SQL where clause field, specify the SQL "WHERE" statement that will identify the set of rows to be exported, in DAL notation. For example, client.id='1000001'
- To export all columns, select the Include All Columns option. To include only the columns you specify, select the Columns tab and create a new record for each column you want to export.
- To include the security audit columns (created, createdby, updated and updatedby) in the export, clear the Exclude Audit Info checkbox.
- Clear the Is Business Object option.
- Click Save
- Click the Export Reference Data button to export the reference data to an .xml file that you can include in the module.
Exporting the database
The next stage is to export the database to create the necessary module folders.
- Execute the command:
ant export.database
- Exporting the database creates a new subfolder within the Modules folder. The new folder has the same name as the java package of the translation module, for example modules/org.openbravo.referencedata.coa.ES_es.
Packaging the module as an .obx file
To package the module, execute the command ant package.module -Dmodule=modulename, where modulename is the Java package name of the module.
Publishing the module to the Openbravo Forge
You are now ready to publish the module to the Openbravo forge
Publishing the module to the Openbravo forge
Once you have created the .obx file, you can make it available to the community via the openbravo forge:
- In a web browser, navigate to the Openbravo forge
- In the Toolbox area, click Register Project.
- Complete the details of your module.
- Click Next.
- On the Services page, select the services you want to be avaiable for your project, for example a discussion forum.
- Click Finish.
- In the Toolbox area, select My Profile.
- In the My Modules area you will see that the module you registered in Openbravo ERP is listed. Click the module.
- To associate the module with the project you have created, select the project from the list. NOTE: Only projects without module associated will appear to be chosen
- Click Associate Project. The Publish Version page appears.
- Click Browse. Navigate to the location of your module's .obx file.
- Click Publish OBX File.
Special case: Initial Setup Reference Data
Starting from MP19 core provides a dataset with client/organization access level. It is available for applying to a new client or organization in the initial client/organization setup windows. The content of this dataset is, nowadays, the Standard Document Types to be created for the newly created client/organization, and all the collaterals needed for this, for example, sequences, jasper templates or g/l categories. Please notice that this dataset can be applied to clients, but also to organizations. Actually that is the best practice - have document types applied to the legal entities in the system. This way, if the company needs to create another legal entity that requires different configuration (document types, templates, etc), there will be no problem.
Any extension module can complement or extend Initial Setup Reference Data dataset. Let's evaluate it based on the example.
John is localizing Openbravo ERP for the region New Kingdom. New Kingdom authorities are very strict on the format and information provided in the invoices issued by every company in the region. Actually standard templates in the ERP for AP Invoice and AR Invoice documents are not valid, and as part of the localization new jasper templates have to be developed and released as an extension module.
John, then, performs an Initial Client Setup where the core dataset is NOT activated. The system will let him know that an important dataset has not been selected, therefore after the client is created, he will need to complete its configuration by either applying a datase to one of its organization or performing the configuration manually.
Then in the new client, performs a Initial Organization Setup, this time applying the core reference data module, as shown in the image:
(IMPORTANT: Being the first organization created in the system which applies the dataset, so first time the dataset is applied)
This will add:
- Document type named AP Invoice
- Template configuration for AP Invoice document type
- Document type named AR Invoice
- Template configuration for AR Invoice document type
Then John modifies the template for AP Invoice and AR Invoice documents mapping to the jasper report created by him to address New Kingdom authorities requirements. After that creates a module containing this jasper report, and with a dataset of data access level client/organization. This dataset is exported, and just the modified entries in c_poc_doctype_template table are included. This module is then packaged as Document type template for New Kingdom. As every other module, it will depend on a concrete version of core module.
Afterwards, this module is installed in a fresh instance. When accessing to initial organization setup window, both reference data sets are selected. System will, first, apply core module (according to set dependencies). Then will apply the module Document type template for New Kingdom, which dataset contains a row that will replace the one of the template for AP / AR Invoice documents.
Combining localization modules into packs
Creating localization packs offers a convenient way for users to implement localization modules. Packs are a particular type of module which consist of other modules, and creating a pack has a specific registration process. Once you have created the localization modules you require, follow these steps to combine them as a pack.
- Log into Openbravo with the system administrator role.
- From the Application menu, select Application Dictionary > Module.
- Click New. A new module record appears.
- In the Name field, give the package a name using the correct naming conventions.
- From the Module Type list, select Package.
- Complete the Description and Help fields using natural language and supplying as much information about the package as possible.
- Complete the rest of the module information as appropriate.
- Click Save
- Select the Include tab.
- Click New.
- From the Included module list, select the module you want to add to the pack.
- Click Save.
- Repeat steps 10-12 to include further modules in the pack.
- Package the module using following ant command: ant package.module -Dmodule. The parameter of the command is the java package name of the translation module. For example if the localization pack is called org.openbravo.package.czechlocalizationpack.CZ_cs,
- the full ant command would be:
ant package.module -Dmodule=org.openbravo.package.czechlocalizationpack.CZ_cs
Once you have created the pack, you can publish it to the Openbravo Forge in the normal way.
This category currently contains no pages or media.