Localizing WSO2 Carbon Products - Part 2

How to generate language fragment bundles to localize Carbon products

In this last blog post, I explained what is localizing, why we need to localize and also why we go ahead with the fragment bundle approach when it comes to localizing WSO2 carbon products.

So as I promised in the last post, will explain how to generate language fragment bundles. 

1. First find out the ui bundles in CARBON_HOME/repository/components/plugins/ that contain Resources.properties files which you need to localize.
2. And then pack resource files in the folder structure with the proper naming conventions. See the example below.

IMPORTANT: Note that folder names (such as org.wso2.carbon.claim.mgt.ui_4.2.0 ) should be named with the original bundle name and the version. ( I will explain later why you need to do so. )

  3. Once you have created the  resource files packed in the correct folder structure, place them in the           CARBON_HOME/resources folder. 

   4.  And navigate to the CARBON_HOME/bin and run the following command.

ant localize

    5. Now go to the CARBON_HOME/repository/components/dropins/. You will see the generated language bundles that you can use to localize.

NOTE: In case if you want to change the location of your resource files or stored location you can change it by passing those as parameters to the ant command.

ant localize -Dresources.directory=/data/blog/wso2is-4.5.0/myResources/ -Ddropins.directory=/data/blog/wso2is-4.5.0/myDrpoins/

But regardless your resource file location, after the generation of fragment bundles, you need to place them in the CARBON_HOME/repository/components/dropins/ directory.

   6. Now you change the locale through browser setting or pass as a query param to the url. And you will observe your page is being localized. Switch between locales and observe that the product getting changed with the new language.

Story behind ant task

In what ever the product you choose to localize, open the build.xml file at CARBON_HOME/bin. Bit down there in that file, there is an ant task called localize.

If you go through this ant task closely, you may note that the folder name of the resources files are spitted and assigned as fragment host and version.

Also note that default locations of resources directory is set to CARBON_HOME/resources while dropins directory is set to CARBON_HOME/repository/components/dropins/

Acknowledgement
My thanks goes to Sumedha at WSO2 for his tremendous support given during this task.

Localizing WSO2 Carbon Products - Part 1

Introduction to Localization of Carbon products 

WSO2 products are used all over the world and it's users may need to translate a product into different languages when adapting that particular product into their country or region. This process of translating the product into different languages is known as Localization.

If you open up any WSO2 product and go inside CARBON_HOME/repository/components/plugins, you will see number of jar files. Among those jars the ones that have their names end with ui_<version>.jar are usually the bundles that contains the resources files that needs to localization.

For an example, let's take WSO2 Identity Server 4.5.0 and go to repository/components/plugins. From that let's select org.wso2.carbon.claim.mgt.ui_4.2.0.jar. Open up the jar using an archive manager or in any preferred way. You may observe folder structure similar to this.

The file you see at the very end; Resources.properties file is the one which the page in the UI used to read string values from. If you open the Resources.properties file you'll observe that it contains some name value pairs as below.

claim.mgt=Claim Management

claim.add=Add

add=Add

cancel=Cancel

claim.management=Claim Management

new.claim.details=New Claim Details

First make a copy of this file and name it with the code of the locale of your preferred language. For an example if you want to localize to French, name of your file should look like Resources_fr.properties. And then you need to change the value of the name value pairs to go with your language. For an example you might change the first pair as follows.

claim.mgt=Gestion des réclamations

In order to localize the whole product, you need to add a resource file for each ui bundle with your desired language.

NOTE:
You can have any number of resource files inside one jar as follows. ( So that you can switch between different languages very easily.)

After that go ahead and change the locale either through browser settings or passing the locale through a url parameter ( as locale=fr ). Now if you refresh the page you will see the page being localized in your preferred language.

But the problem with this approach is that if you happen to patch any of these jars, you will have to update the Resources.properties file of your preferred language every time that you do so.

So the recommended approach is to localize through fragment bundles which gets attached to the specified host. In my next post I will be explaining how to generate the fragment bundles to localize WSO2 carbon products.