About the Author

Elbert Bautista

Software Architect

in Development 5 min read

i18n Enhancements for 3.2 and Enterprise

Internationalization enhancement to the core framework and a new enterprise module

We're happy to announce that with the 3.2 GA of the core framework, several internationalization enhancements have been introduced that will make it easier to work with i18n messages, forms, translations, and addresses.

Internationalized Address Enhancements

We've refactored our Address domain to reference a new entity called ISOCountry BLC_ISO_COUNTRY which represents the ISO 3166 standard published by the International Organization for Standardization (ISO). On this entity, we've deprecated the use of the Country and State foreign key fields that were previously used. In addition, the State BLC_STATE table is completely deprecated in favor of a new entity called CountrySubdivision BLC_COUNTRY_SUB which aims to represent the ISO 3166-2 codes for identifying the principal subdivisions of the countries in the BLC_COUNTRY table. These changes help support several things:

  • A more accurate domain to model international addresses and maximize data quality
  • Ability to separate filtering of supported countries from saving a generic address. For example, your business may only wish to support shipping to certain countries (which you can do by populating the BLC_COUNTRY table), however that shouldn't mean developers need to create something custom to accommodate users with a billing address in another "unsupported" country. Decoupling an address from BLC_COUNTRY in favor of using the BLC_ISO_COUNTRY table helps alleviate this problem
  • Easier integration with third party providers that manage addresses outside the Broadleaf system. For example, payment and digital wallet solutions usually manage address information. In most cases, these providers support the ISO standard which makes integration with the Broadleaf system much easier

If you are currently running a version of Broadleaf prior to 3.2, you can view more of the details regarding these enhancements and what migration steps are needed to support the changes here: http://www.broadleafcommerce.com/docs/core/3.2/migration-notes/3.1.1-to-3.2-migration

i18n Enterprise Features

In addition to our core framework enhancements, we've also created a separate module that adds even more more i18n features to help you manage your global eCommerce site. When you include the i18n Enterprise module in your project, you will get a new section in your Admin console that will allow you to manage all your internationalized translations, messages, and forms in one convenient place.

i18nEnterprise Admin

Dynamic Regional Address Form

Let's face it, nobody likes to fill out forms online. Studies have shown that checkout forms which are simple and offer the lowest resistance have the highest conversion rates. This is obvious. However, what may be less obvious is that forms that are considered "easy" and "simple" for a user in one country, may not be "easy" for a user in another country.

There was a good article online that described some of the falsehoods many programmers believe about Address validation. Did you know that Ireland does not use a Postal Code? (although this is supposed to change soon as there are plans to implement one in Spring of 2015 http://en.wikipedia.org/wiki/Postal_addresses_in_the_Republic_of_Ireland) In fact, there are over 50 different territories all over the world that don't use a postal code. How many times have you seen an address form that supposedly allows you to ship anywhere around the world, but the postal code field is required? What about forms that ask for a first and last name that are both required? Many spanish-speaking people commonly have two family names. Many people in southeast Asia have only one given name. How do people usually deal with forms that are catered to a specific cultural standard that don't apply to them? In most cases with frustration and fake data. In some cases they just give up and abandon their cart. How would you feel if you were trying to purchase something online, but couldn't figure out how to ship it to yourself because you couldn't get pass the address form?

Consider the fact that there are over 240 countries and territories, 140 different address formats, 6000+ languages written in various scripts, and over 40 personal name formats. Building a simple generic catch-all form to handle this can be daunting and in most cases wrong.

Having said that, there are best practices when dealing with international addresses online. We've considered all of these best practices and come up with a solution that aims to alleviate the issues faced when running an international business online that provides an easy way to build and manage dynamic forms based on region. Using this module, you can create address forms that are dynamic based on the country that you select. For example, if you wish to ship your order to Germany, but the billing address is in Brazil, you may have forms that look like this:

i18nEnterprise Shipping Form - Germany

i18nEnterprise Billing Form - Brazil

This gives you the ability to take into account local and cultural norms, as well as the order of fields that are standard to a particular region. You will be able to easily add, remove, and order the fields on this form directly from the Admin.

Managing Translations and Messages

The i18n Enterprise module also gives you the ability to easily manage all the Translations and Messages of your eCommerce site through the Admin. The difference between a translation and a message in our system, would be that a translation is a field that is user generated and can be managed in the Admin. An example of a Translation would be something like a Category name or description field. You can enter the name of the Category in English, but also associate that field value to a localized translation as well.

A message on the other hand, is defined as a localized string that is known at compile time. Messages are currently handled through the use of Spring's Message Source and ResourceBundles. By including this module, you can intercept this and store all your localized messages in the Admin (Database). If there is a resource with a locale string that matches in the database it will use that one first, otherwise it will fall back to the default Spring Message source resolution. This way you can dynamically add messages without having to do another deployment!


We hope with these enhancements, you can build and maintain your international eCommerce site more easily and effectively. In the meantime, keep a look out as we continue to improve our i18n offerings!