Welcome!

You will be redirected in 30 seconds or close now.

ColdFusion Authors: Yakov Fain, Jeremy Geelan, Maureen O'Gara, Nancy Y. Nee, Tad Anderson

Related Topics: ColdFusion

ColdFusion: Article

Add Localization to Your Web Site

Adapting an application to a specific locale

Welcome to another installment of Extending ColdFusion. In this edition, we are going to look at one of the ways you can add localization to your Web site. What do we mean by localization? Localization or L10N (L10N is an abbreviation for the 10 letters between the "L" and "N" in localization) describes the process of adapting an application to a specific locale.

You can think of L10N as the process of applying a locale or language "skin" to an application. That can mean many things like date, currency, and number formatting; calendars; text direction, and so on. Typically localization is done after a process called internationalization. Internationalization or I18N (I18N is an abbreviation for the 18 letters between the "I" and "N" in internationalization) is the design and development of an application so that it functions in at least two locales. You can think of I18N as making an application language or locale neutral.

In this article we are going to focus on one aspect of localization, and that is the site user interface and static text. In a later edition we will talk about how dynamic content can be localized. We are going to talk specifically to the concept of "resource bundles." These are files that contain a set of translations. For example, here is a representation of a simple English resource bundle:

Cancel=Cancel
Save=Save

Not very exciting, but the basic concept here is that we have a list of keys (the strings on the left side of the equal signs) and values (the strings on the right side). This becomes clearer when we look at the French version of the bundle:

Cancel=Annuler
Save= Enregistrer

As you can see, we have the exact same keys, but the strings on the right-hand side, the actual values, are the French versions. Extending this a bit farther, you can use a larger set of keys and values, one key for each piece of text on your Web site. To add support for a new language, you simply create a new resource bundle and do the translations. You should understand that managing the translation of resource bundles can become quite a task for anything complicated. One of the more popular tools for this task is IBM's Java-based rbManager, which you can download from http://oss.software.ibm.com/icu4j/demo_tools/RBManager.html.

One note about resource bundles: we use a Java object, java.util.PropertyResourceBundle, to handle parsing in the resouce bundle. This Java object requires that the resource bundle files be encoded using escaped ASCII. For example, here is the Thai version of "Cancel": \u0E22\u0E01\u0E40\ u0E25\u0E34\u0E0. Besides the rbManager tool mentioned above, Sun provides a command-line tool, native2ascii, that handles the creation of properly escaped Unicode text. This program is included in the "bin" directory of standard Java installs. You can find documentation for it at: http://java.sun.com/j2se/1.4.1/docs/tooldocs/windows/native2ascii.html.

How do we use this in ColdFusion? Listing 1 demonstrates a simple CFC that we will use to load resource bundles and display them on our Web site. Let's begin by looking at the getResourceBundle method. This method will take a resource bundle and return a structure of keys and values. The method takes two arguments. The first argument is the file name of the resource bundle. (We actually do some magic with this argument, which I will go into a bit later.) The second argument is optional, and represents the locale. Java uses a different format for locales than ColdFusion. Notice how the default is "en_US." In CFML, this is the same as English (US).

After initializing our arguments, we then have a set of var statements. Do not forget that it is vital to var scope any variable created with a CFC method. As I said above, we are going to do some magic with the resource bundle file name. If the file doesn't exist as passed, we check to see if a locale version exists. What do we mean by that? Imagine you have a set of resource bundles in your c:\projectX\resources\text folder. Each one is named "language_en_US.properties", where the only part of the name that changes is the locale version. In other words, the French version would be "language_fr_FR.properties." The getResourceBundle method allows us to simply pass in "c:\projectX\resources\text\language.properties" as the file name. When it discovers that the file does not exist, it will automatically try to load "c:\projectX\resource\text\language_en_US.properties". This is because the rbLocale argument defaults to en_US; to load the French version you would simply pass in fr_FR.

Once the method finds the file (it will throw an error if it cannot), we then use a set of Java objects we created in the constructor area of the CFC:

<cfscript>
variables.rB = createObject("java", "java.util.PropertyResourceBundle");
variables.fis = CreateObject("java", "java.io.FileInputStream");
</cfscript>

These objects then enable getResourceBundle method to load the properties file:

variables.fis.init(arguments.rbFile);

and then initialize the PropertyResourceBundle object:

variables.rB.init(variables.fis);

Once we have done that, we can use another method, getKeys(), to get the keys of the resource bundle. We then simply loop over our keys and create a structure of the values. Once we have the structure we return it.

So, let's take a quick look at how this could be used on a sample page. Listing 2 contains a simple form, in this case, one with just a submit and cancel button. However, the labels for these buttons need to be localized. To get the correct strings, we use <cfinvoke> to get the resource bundle from a property file, and to specifically grab the fr_FR version. We can then use this returned structure to populate the values of our buttons. As you can see from the code, switching to English would be a trivial change.

Let's take a look at another method in the CFC, loadResourceBundle. This is an extremely short method. All it does is take a file and an optional locale. It calls the getResourceBundle method we described earlier, and then stores it in the CFC's local variable scope. This allows us to create an instance of the CFC and have it parse the resource bundle once.

Finally, the method getResource allows us to grab one particular string from the structure. Why would you use this when you could getResourceBundle? This method will slightly modify the result when debugMode is detected. Instead of returning just the string, it will actually return the string wrapped in * characters. Visually, this makes it easy to see which parts of your page are localized and which are not. This method will also "swallow" any errors that involve missing resources, so if you try to retrieve a resource for the French locale that doesn't exist, you will get a blank string. (This may or may not be preferable. What's nice is that you can modify the CFC to handle it differently. You may want it to retrieve the en_US version if one doesn't exist for the fr_FR version. You could also have it optionally log a warning, or e-mail a localization team.)

One more example before we end. In the code in Listing 2, we had a hard-coded locale. Normally you probably want your user to select a locale. You may think it's a good idea to store the resource bundle in the user's session scope. However, this means that every user in locale N will have a copy of the bundle, which isn't efficient. Listing 3 shows a modified version of Listing 2. This time we allow the user to select a locale. We store the user's preference, but keep the bundles stored in the application scope.

The author wishes to give special thanks to Paul Hastings, who he says is, without a doubt, the localization/internationalization master, and was a big help in writing this article. His blog can be found at http://cfg11n.blogspot.com. (Watch for a series by Paul in future issues of CFDJ.)

More Stories By Ray Camden

A longtime ColdFusion user, Raymond is a co-author of the "Mastering ColdFusion" series published by Sybex Inc, as well as the lead author for the ColdFusion MX Developer's Handbook. He also presents at numerous conferences and contributes to online webzines. He and Rob Brooks-Bilson created and run the Common Function Library Project (www.cflib.org), an open source repository of ColdFusion UDFs. Raymond has helped form three ColdFusion User Groups and is the manager of the Acadiana MMUG.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


@ThingsExpo Stories
SYS-CON Events announced today that Enzu will exhibit at SYS-CON's 21st Int\ernational Cloud Expo®, which will take place October 31-November 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. Enzu’s mission is to be the leading provider of enterprise cloud solutions worldwide. Enzu enables online businesses to use its IT infrastructure to their competitive advantage. By offering a suite of proven hosting and management services, Enzu wants companies to focus on the core of their ...
With major technology companies and startups seriously embracing Cloud strategies, now is the perfect time to attend 21st Cloud Expo October 31 - November 2, 2017, at the Santa Clara Convention Center, CA, and June 12-14, 2018, at the Javits Center in New York City, NY, and learn what is going on, contribute to the discussions, and ensure that your enterprise is on the right path to Digital Transformation.
Internet of @ThingsExpo, taking place October 31 - November 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA, is co-located with 21st Cloud Expo and will feature technical sessions from a rock star conference faculty and the leading industry players in the world. The Internet of Things (IoT) is the most profound change in personal and enterprise IT since the creation of the Worldwide Web more than 20 years ago. All major researchers estimate there will be tens of billions devic...
Amazon started as an online bookseller 20 years ago. Since then, it has evolved into a technology juggernaut that has disrupted multiple markets and industries and touches many aspects of our lives. It is a relentless technology and business model innovator driving disruption throughout numerous ecosystems. Amazon’s AWS revenues alone are approaching $16B a year making it one of the largest IT companies in the world. With dominant offerings in Cloud, IoT, eCommerce, Big Data, AI, Digital Assista...
SYS-CON Events announced today that Cloud Academy named "Bronze Sponsor" of 21st International Cloud Expo which will take place October 31 - November 2, 2017 at the Santa Clara Convention Center in Santa Clara, CA. Cloud Academy is the industry’s most innovative, vendor-neutral cloud technology training platform. Cloud Academy provides continuous learning solutions for individuals and enterprise teams for Amazon Web Services, Microsoft Azure, Google Cloud Platform, and the most popular cloud com...
When growing capacity and power in the data center, the architectural trade-offs between server scale-up vs. scale-out continue to be debated. Both approaches are valid: scale-out adds multiple, smaller servers running in a distributed computing model, while scale-up adds fewer, more powerful servers that are capable of running larger workloads. It’s worth noting that there are additional, unique advantages that scale-up architectures offer. One big advantage is large memory and compute capacity...
No hype cycles or predictions of zillions of things here. IoT is big. You get it. You know your business and have great ideas for a business transformation strategy. What comes next? Time to make it happen. In his session at @ThingsExpo, Jay Mason, Associate Partner at M&S Consulting, presented a step-by-step plan to develop your technology implementation strategy. He discussed the evaluation of communication standards and IoT messaging protocols, data analytics considerations, edge-to-cloud tec...
"When we talk about cloud without compromise what we're talking about is that when people think about 'I need the flexibility of the cloud' - it's the ability to create applications and run them in a cloud environment that's far more flexible,” explained Matthew Finnie, CTO of Interoute, in this SYS-CON.tv interview at 20th Cloud Expo, held June 6-8, 2017, at the Javits Center in New York City, NY.
SYS-CON Events announced today that MobiDev, a client-oriented software development company, will exhibit at SYS-CON's 21st International Cloud Expo®, which will take place October 31-November 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. MobiDev is a software company that develops and delivers turn-key mobile apps, websites, web services, and complex software systems for startups and enterprises. Since 2009 it has grown from a small group of passionate engineers and business...
SYS-CON Events announced today that GrapeUp, the leading provider of rapid product development at the speed of business, will exhibit at SYS-CON's 21st International Cloud Expo®, which will take place October 31-November 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. Grape Up is a software company, specialized in cloud native application development and professional services related to Cloud Foundry PaaS. With five expert teams that operate in various sectors of the market acr...
SYS-CON Events announced today that Ayehu will exhibit at SYS-CON's 21st International Cloud Expo®, which will take place on October 31 - November 2, 2017 at the Santa Clara Convention Center in Santa Clara California. Ayehu provides IT Process Automation & Orchestration solutions for IT and Security professionals to identify and resolve critical incidents and enable rapid containment, eradication, and recovery from cyber security breaches. Ayehu provides customers greater control over IT infras...
We build IoT infrastructure products - when you have to integrate different devices, different systems and cloud you have to build an application to do that but we eliminate the need to build an application. Our products can integrate any device, any system, any cloud regardless of protocol," explained Peter Jung, Chief Product Officer at Pulzze Systems, in this SYS-CON.tv interview at @ThingsExpo, held November 1-3, 2016, at the Santa Clara Convention Center in Santa Clara, CA
With the introduction of IoT and Smart Living in every aspect of our lives, one question has become relevant: What are the security implications? To answer this, first we have to look and explore the security models of the technologies that IoT is founded upon. In his session at @ThingsExpo, Nevi Kaja, a Research Engineer at Ford Motor Company, discussed some of the security challenges of the IoT infrastructure and related how these aspects impact Smart Living. The material was delivered interac...
Artificial intelligence, machine learning, neural networks. We’re in the midst of a wave of excitement around AI such as hasn’t been seen for a few decades. But those previous periods of inflated expectations led to troughs of disappointment. Will this time be different? Most likely. Applications of AI such as predictive analytics are already decreasing costs and improving reliability of industrial machinery. Furthermore, the funding and research going into AI now comes from a wide range of com...
In his session at Cloud Expo, Alan Winters, an entertainment executive/TV producer turned serial entrepreneur, presented a success story of an entrepreneur who has both suffered through and benefited from offshore development across multiple businesses: The smart choice, or how to select the right offshore development partner Warning signs, or how to minimize chances of making the wrong choice Collaboration, or how to establish the most effective work processes Budget control, or how to ma...
IoT solutions exploit operational data generated by Internet-connected smart “things” for the purpose of gaining operational insight and producing “better outcomes” (for example, create new business models, eliminate unscheduled maintenance, etc.). The explosive proliferation of IoT solutions will result in an exponential growth in the volume of IoT data, precipitating significant Information Governance issues: who owns the IoT data, what are the rights/duties of IoT solutions adopters towards t...
In his session at @ThingsExpo, Eric Lachapelle, CEO of the Professional Evaluation and Certification Board (PECB), provided an overview of various initiatives to certify the security of connected devices and future trends in ensuring public trust of IoT. Eric Lachapelle is the Chief Executive Officer of the Professional Evaluation and Certification Board (PECB), an international certification body. His role is to help companies and individuals to achieve professional, accredited and worldwide re...
SYS-CON Events announced today that CA Technologies has been named "Platinum Sponsor" of SYS-CON's 21st International Cloud Expo®, which will take place October 31-November 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. CA Technologies helps customers succeed in a future where every business - from apparel to energy - is being rewritten by software. From planning to development to management to security, CA creates software that fuels transformation for companies in the applic...
SYS-CON Events announced today that IBM has been named “Diamond Sponsor” of SYS-CON's 21st Cloud Expo, which will take place on October 31 through November 2nd 2017 at the Santa Clara Convention Center in Santa Clara, California.
In this presentation, Striim CTO and founder Steve Wilkes will discuss practical strategies for counteracting fraud and cyberattacks by leveraging real-time streaming analytics. In his session at @ThingsExpo, Steve Wilkes, Founder and Chief Technology Officer at Striim, will provide a detailed look into leveraging streaming data management to correlate events in real time, and identify potential breaches across IoT and non-IoT systems throughout the enterprise. Strategies for processing massiv...