Saturday, October 5, 2013

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 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
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/

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


  1. Hi there!

    After ant localize command I tried to start the server but it stopped at some point, why is that?

    zygimantus@zygimantus-pc:~/opt/wso2dss-3.2.2/bin$ sudo JAVA_HOME=/usr/lib/jvm/java-7-oracle ./
    JAVA_HOME environment variable is set to /usr/lib/jvm/java-7-oracle
    CARBON_HOME environment variable is set to /home/zygimantus/opt/wso2dss-3.2.2
    --------NO OUTPUT HERE!------

  2. Hi, thanks a lot, this information is very useful
    for zygimantus problem, when run ant localize its finds every folder in CARBON_HOME/resources and build a jar in CARBON_HOME/repository/components/dropins/
    the folder CARBON_HOME/resources/allthemes build
    ${}.languageBundle_${fragmentHost.version}.jar in CARBON_HOME/repository/components/dropins/, delete this and run the server (tested in wso2is-5.3)