How to Create Localization Packs
| Languages: |
English | Translate this article... |
Contents |
About this document
This document is part of the Localization Guide for Openbravo and describes the way to create localization packs for Openbravo. It is divided into two main sections:
- A general explanation about the parts that can be localized. It is written from a functional perspective and aims to provide the reader with a high-level perspective on the elements included into a common localization for Openbravo, and the way to package and distribute it to the end-users.
- A technical part with the concrete steps to create and to update a localization pack.
Functional explanation
According to wikipedia, internationalization and localization are means of adapting computer software to different languages, regional differences and technical requirements of a target market. The final objective of a localization is to improve the end-user's experience inside a region.
Openbravo is an ERP ready to be localized. Due to the Openbravo Modularity capabilities, almost every area you can imagine can be the target of a localization. That means that Openbravo can be easily adapted to the needs and legal requirements of any region.
Although the list can be very long, these are the elements that are usually involved into a common localization for Openbravo:
Translation
When we think about a localization, probably the first area we think about is the translation, and it is evident it could be the most important area. The user will definitely feel more comfortable if the software is available for his language.
Openbravo fully supports the translation of the User Interface to any language (even RTL languages), which includes the Application Menu, Windows, Tabs, Fields, Reports, Messages, and everything else you can imagine. Apart from the User Interface, Openbravo also allows the translation of what we call Masterdata, which for example represents the Currency names, Countries or Month names.
But the translation support goes beyond that, and Openbravo is also ready for supporting the translation of third party extensions. This basically means that we can create and distribute the translation of an extension developed by other person or company, ensuring this way that the end-user has always a fully translated application.
Chart of Accounts
Apart from translations, a good localization for any country must also include the Chart of Accounts for that country, which is the tree of the most common used accounts in the country. This list is imported into each instance of the ERP and it is used by the accounting engine. Later on, based on this list, the end-user can get meaningful financial reports such as Balance Sheet and P&L.
Depending on the country laws, more than one chart of accounts may be available, for example depending on the enterprise size, or the main areas of business. For example, in the localization for Spain we provide a Chart of Accounts for the small and medium size enterprises, and another one for other companies.
On the other hand a statutory chart of accounts is not a localization requirement in many countries due to differences in commercial law. In some countries (influenced by the UK or the US), you may use any accounts you like, and you may change them over time according to business needs. Even for these cases it is necessary to provide a sample Chart of Accounts to make it easier and faster for the user to configure his instance.
Taxes
Taxes are probably the third most important element in a localization for Openbravo. Each country usually has a list of most common tax rates (and withholding) used for transactions, like for example international imports and exports of goods, tax rates for services, etc.
The evident benefit of providing a good taxes configuration is to accelerate the ERP initial setup done by the end-users, but this is not the only advantage. If we provide this configuration, we can take control over the taxes our users are using in their transactions and, as a consequence, we can identify the type of transaction depending on the tax rates involved. So, based on the taxes configuration, we can later on develop official fiscal reports for this country based on these well-known taxes rates.
Regions
Some countries, like Spain, are internally divided into regions, making them a perfect candidate for the localization. If we provide the list of regions for a the country, we make it easier for the end-users to work with addresses. But this is not the only advantage; the regions configuration may allow us to develop new extensions that depend on the region definition.
For example, imagine that the legal definition of tax in a country varies according to regions. In this scenario, the taxes configuration that we have commented before will mandatory depend on a good regions definition.
Payment Terms
A payment term specifies the way and period allowed to pay off an amount due. For example, a business partner may demand a deferred payment period of 30 days or may even demand to partially pay their debts or collects in two or more deferred periods. Although the payment terms depend on the agreements between the organization and the business partners, there is usually a list of the common payment terms applied in a country, making it a perfect candidate for a localization.
Payment Methods
Similar to payment terms, payment methods are other good candidates for a localization.
Payment Methods represents means of payment used by enterprises or business partners, like cash or credit card. Based on the Payment Method configuration, Openbravo automatically defines a particular payment flow.
Validating data
The list of elements we have commented so far have no new functionality, i.e. they just contain data (taxes, regions, accounts, payment terms, payment methods and translations). However, Openbravo allows to extend the ERP features with code that implements some kind of business logic, like new validations.
For example, we may be interested in developing some code to validate that the Business Partner Tax ID or bank account number introduced by the end-user observes the legal format for our country. All this kind of validations can be easily included into a localization for Openbravo.
Overriding accounting
The accounting entries generated by Openbravo are usually fine in most scenarios, however there could be the case where these entries don't fulfill the legal requirements for a concrete country, making it necessary to generate them in a different way.
To support this kind of requirements, Openbravo allows to override the default accounting entries. To make it possible we must develop the code that implements the new logic for creating the accounting entries. This code can also be part of the localization for our country.
Extending the accounting behaviour
Flexibility and extensibility are two important Openbravo features. An example of them is the ability to run processes just after the posting logic for any document has been successfully completed, like for example keep an up-to-date log of the posted documents, update some kind of official reports each time a transaction is posted, etc.
Depending on your requirements this feature can be very useful and it can also be included into your localization project.
Official fiscal reports
Companies are forced to submit a set of official fiscal reports to the Administration on a regular basis. Tax Authorities usually allow companies to submit online their fiscal reports which must observe a concrete structure defined by the Authorities. Including the most common official fiscal reports as part of the localization is definitely the killing feature every end-user is looking for.
Openbravo provides a framework that, along with a good taxes definition, makes it easier to develop this kind of fiscal reports.
Remittance files
A remittance is a group of payments which can be remitted to the bank. The bank will then manage either the collection of the money from the customers or the payment to the vendors/suppliers. The list of payments the bank must manage is usually included into a plain text file with an official structure defined by the bank.
As we have seen before in the case of fiscal reports, Openbravo also provides another framework that simplifies the development of this kind of remittance files, and which can also be included in the localization.
Technical explanation
Modules, dependencies and Packages
Since the 2.50 version, Openbravo supports the concept of Modularity, which is a feature that allows the developer to easily extend the ERP capabilities. The way to develop and distribute a localization is in the form of modules and packages.
A module is the simplest unit to encapsulate concrete developments (related to localization or not). All the elements usually involved into a localization for Openbravo are developed in individual modules, for example, a Taxes module, a Regions Module, a Chart of Accounts module for the small and medium size enterprises, a module for the Official Fiscal Report “DummyReport”, etc.
The functionality included in a module must be something concrete and isolate, don't try to mix different concepts into the same module. For example, if your taxes configuration varies according to the regions in your country, then first create a Regions module and after that the Taxes module which will depend on the Regions one.
This kind of dependencies are declared when creating the modules, and are automatically managed by Openbravo at installation time. Thus, in the previous example, when trying to install the Taxes module, the system automatically downloads and installs the Regions module to satisfy the dependency.
The localization for a country may contain a great number of modules. To make it easier to distribute and deploy a localization, we can encapsulate the modules into packages. A package is a special type of module which contains no functionality, but just a set of modules. Later on we will see how to create a localization pack.
Structure for a localization pack
The localization for a country may include a large number of modules with different functionality; in fact it should ideally include all the necessary modules to fully localize Openbravo for a concrete country.
The absolute minimum objective for a localization project is to have the following functionality:
- Translation: the user interface needs to be translated to the region's language. This implies the creation of a translation pack that includes the translation for all the modules distributed with Openbravo.
- Chart of accounts: the structure and rules that govern accounting according to the local practices and/or regulations. Even for the countries where an official Chart of Accounts does not exist, we must also include a sample Chart of Accounts module that the companies can take as a base for defining their own account trees.
- Taxes module with the most common tax rates used in a country.
In most countries this is all you need to start using Openbravo.
However, we do encourage to go beyond the minimum requirements, and to develop all the necessary extensions that make possible the localization for the country. This generally includes all the elements we have seen before: regions, payment terms, payment methods, official fiscal reports, remittance files, and everything else you think it is important for the localization of your country.
Community versus Professional localization packs
Modules and packages can be distributed either as a Commercial or Non-Commercial way.
Non-Commercial way, which is usually called Community Edition, implies the modules and packages are distributed under a free software license, and can be installed in any Openbravo instance for free.
All the countries where a localization pack is ready must mandatory have available a Community Edition localization pack which includes at least the basic localization elements: translation, chart of accounts and taxes.
However, some partners may offer a Commercial Professional Edition localization which ensures local compliance and updates, based on contractual service level agreements. Professional localizations can be offered with a proprietary license as long as open source localization exists for that market.
The commercial modules and packages can only be installed into Openbravo Professional Edition instances, which is a way to improve even more the experience of the Professional Edition subscribers.
Creating the Localization Pack
As you know the localization pack is just a container for a list of individual modules (or other packages). It is obvious that before creating the localization pack you must develop first the modules you want to include in.
As part of the Localization Guide, Openbravo provides a list of very detailed howtos that cover the most common modules usually included into a localization pack. This doesn't mean you must stack to that list, remember that you should include any additional functionality you think it is important for the localization of your country.
Localization Pack Community Edition
The Community Edition of any localization pack must include at least the translations, chart of accounts and taxes.
Translation Pack
The translation for Openbravo implies creating a translation module for all the modules included into the distribution. Please read the How to Create and Update Translation Modules for more information about this process.
At the time this document has been written, there are 15 modules included in the Openbravo distribution that need to be translated. As you can see the number is high, so to keep all of them under control, we can create a package that includes all of them. This is called the Translation Pack.
Creating this translation pack is quite easy and does not require any special skill. We just need to be sure that the instance where we are going to create the translation pack already has installed all the translation modules that will be part of it.
So, as System Administrator we go to the Application Dictionary || Module window and we create a new record following this considerations:
- You should try to follow the Naming guidelines for modules. Remember that the name must be written in English, even for non-English modules.
- The type must be set to Package
- Write an author name and the URL, that usually corresponds to the forge project, as http://forge.openbravo.com/projects/xxxxxx where xxxxxx must be the "Short Name" of the corresponding forge project.
(Remember that every module and/or pack needs to have its corresponding project created in the Forge). - Define the license type and write a short license text.
- The flag Commercial must be set to No, because the translation must be freely available
- Inside the Include tab, define all the modules that will be part of the translation pack
After the package definition is ready, you should register the module in case you want to publish it in the Forge
Now, to generate the obx file we should follow the standard steps from the command line:
- Export the database:
ant export.database
- Package the module:
ant package.module -Dmodule=<translation pack java package>
- We can now publish the module in the Central Repository. Remember that before publishing the pack, you must first publish all the individual translation modules that are part of the package in their respective forge projects.
Creating the Community Edition Localization Pack
Once the translation pack, taxes module and chart of accounts module (and any other interesting module you want to include into the Community Edition) are ready, we can create the Community Edition Localization Pack.
The mechanism is exactly the same as we have seen before for the translation pack. So, in an instance where all the modules and packs that we want to include into the localization pack are already installed, we can go to the Application Dictionary || Module window and create a new record for the pack with the previous considerations:
- You should try to follow the Naming guidelines for modules. These are the specific rules for a localization pack:
- The package name should be written in the official language for the country.
- You can only use the word Official in case you have reached an agreement with Openbravo
- The type must be set to Package
- Write an author name and the URL, that usually corresponds to the forge project
- Define the license type and write a short license text.
- The flag Commercial must be set to No, because the translation must be freely available
- Inside the Include tab, define all the modules/packs that will be part of the localization pack (at least the translation pack, taxes and chart of accounts modules).
After the package definition is ready, you should register the module in case you want to publish it in the Forge
Now, to generate the obx file we should follow the standard steps from the command line:
- Export the database:
ant export.database
- Package the module:
ant package.module -Dmodule=<translation pack java package>
- We can now publish the module in the Central Repository. Remember that before publishing the pack, you must first publish all the individual modules and packs that are part of the package in their respective forge projects.
To provide better support to the users, we recommend enabling the forums and bug tracking features available in the forge project for the Localization Pack. This way the Localization Pack users could ask for feedback or report any issue they may find. |
Localization Pack Professional Edition
A Professional Localization Pack always includes the Community Localization Pack along with other modules related to the localization for a country. It's up to the partner to decide which modules to include into the Professional Edition.
The Community Edition usually contains the localization basis as a mean of attracting new users. However, the Professional Localization Pack often includes the killing modules that really make the difference, and that force the users to subscribe to the Openbravo Professional Edition. Examples of common modules to be included into the Professional Edition are: modules that generates remittance files, official fiscal reports, etc.
Creating the Professional Edition Localization Pack
The theory for creating a Professional Localization Pack is similar to the one we have seen before. Here is the concrete considerations we must take into account:
- You should try to follow the Naming guidelines for modules. These are the specific rules for a localization pack:
- The package name should be written in the official language for the country.
- You can only use the word Official in case you have reached an agreement with Openbravo
- Examples of localization pack names are:
- Official Localization Pack: Australia
- Localización Oficial: México
- Localización Oficial: Argentina
- The type must be set to Package
- Write an author name and the URL, that usually corresponds to the forge project
- Define the license type and write a short license text.
- The flag Commercial must be set to Yes
- Inside the Include tab, define all the modules/packs that will be part of the localization pack, including the Community Localization Pack.
After the package definition is ready, you should register the module in case you want to publish it in the Forge
Now, to generate the obx file we should follow the standard steps from the command line:
- Export the database:
ant export.database
- Package the module:
ant package.module -Dmodule=<translation pack java package>
- We can now publish the module in the Central Repository. Remember that before publishing the pack, you must first publish all the individual modules and packs that are part of the package in their respective forge projects.
To provide better support to the users, we recommend enabling the forums and bug tracking features available in the forge project for the Localization Pack. This way the Localization Pack users could ask for feedback or report any issue they may find. |
Registering the commercial modules and packages into Butler
The professional package and the rest of the commercial modules included into the localization pack must be registered in the Openbravo licensing server.
This is a manual step that requires you to send the list of names and UUIDs of all your commercial modules and packages to Openbravo using standard Openbravo support channels (Support Portal or Support Email).
In the modules folder of your Openbravo working copy you will find a directory per module/pack available in your system. Inside each folder there is a file that contains this information. You can find it in the path:
<Openbravo working copy>/modules/<module/pack java package name>/src-db/database/sourcedata/AD_MODULE.xml
The UUID can be found inside the AD_MODULE_ID element. Example:
<!--D70732EA90A14EC0916078B85CC33D2A--> <AD_MODULE_ID><![CDATA[D70732EA90A14EC0916078B85CC33D2A]]></AD_MODULE_ID>
In this case, the UUID is D70732EA90A14EC0916078B85CC33D2A
You can also take the module's name from the NAME element in this file.
Updating a Localization Pack
Once you have created and published a localization pack (or any other type of package) you may need to release new versions in the future that include bug fixing or new legal requirements. In this case you must always take into account the following rules:
- If you have increased the minor version of any of the modules included into the pack, it is then not necessary to release a new version of the Localization Pack. This is possible because the Central Repository automatically takes the last minor version in the major version of each of the modules included in the package when installing/updating the Localization pack.
- On the other hand, if you want to include any new module into the pack, or even change the major version of any of the modules, you do require to release a new major version of the Localization Pack that includes these new modules.