Click here to close now.

Welcome!

You will be redirected in 30 seconds or close now.

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

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
P2P RTC will impact the landscape of communications, shifting from traditional telephony style communications models to OTT (Over-The-Top) cloud assisted & PaaS (Platform as a Service) communication services. The P2P shift will impact many areas of our lives, from mobile communication, human interactive web services, RTC and telephony infrastructure, user federation, security and privacy implications, business costs, and scalability. In his session at @ThingsExpo, Robin Raymond, Chief Architect at Hookflash, will walk through the shifting landscape of traditional telephone and voice services ...
The 17th International Cloud Expo has announced that its Call for Papers is open. 17th International Cloud Expo, to be held November 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA, brings together Cloud Computing, APM, APIs, Microservices, Security, Big Data, Internet of Things, DevOps and WebRTC to one location. With cloud computing driving a higher percentage of enterprise IT budgets every year, it becomes increasingly important to plant your flag in this fast-expanding business opportunity. Submit your speaking proposal today!
Explosive growth in connected devices. Enormous amounts of data for collection and analysis. Critical use of data for split-second decision making and actionable information. All three are factors in making the Internet of Things a reality. Yet, any one factor would have an IT organization pondering its infrastructure strategy. How should your organization enhance its IT framework to enable an Internet of Things implementation? In his session at Internet of @ThingsExpo, James Kirkland, Chief Architect for the Internet of Things and Intelligent Systems at Red Hat, described how to revolutioniz...
All major researchers estimate there will be tens of billions devices - computers, smartphones, tablets, and sensors - connected to the Internet by 2020. This number will continue to grow at a rapid pace for the next several decades. With major technology companies and startups seriously embracing IoT strategies, now is the perfect time to attend @ThingsExpo, June 9-11, 2015, at the Javits Center in New York City. Learn what is going on, contribute to the discussions, and ensure that your enterprise is as "IoT-Ready" as it can be
The security devil is always in the details of the attack: the ones you've endured, the ones you prepare yourself to fend off, and the ones that, you fear, will catch you completely unaware and defenseless. The Internet of Things (IoT) is nothing if not an endless proliferation of details. It's the vision of a world in which continuous Internet connectivity and addressability is embedded into a growing range of human artifacts, into the natural world, and even into our smartphones, appliances, and physical persons. In the IoT vision, every new "thing" - sensor, actuator, data source, data con...
Container frameworks, such as Docker, provide a variety of benefits, including density of deployment across infrastructure, convenience for application developers to push updates with low operational hand-holding, and a fairly well-defined deployment workflow that can be orchestrated. Container frameworks also enable a DevOps approach to application development by cleanly separating concerns between operations and development teams. But running multi-container, multi-server apps with containers is very hard. You have to learn five new and different technologies and best practices (libswarm, sy...
SYS-CON Events announced today that DragonGlass, an enterprise search platform, will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. After eleven years of designing and building custom applications, OpenCrowd has launched DragonGlass, a cloud-based platform that enables the development of search-based applications. These are a new breed of applications that utilize a search index as their backbone for data retrieval. They can easily adapt to new data sets and provide access to both structured and unstruc...
There's Big Data, then there's really Big Data from the Internet of Things. IoT is evolving to include many data possibilities like new types of event, log and network data. The volumes are enormous, generating tens of billions of logs per day, which raise data challenges. Early IoT deployments are relying heavily on both the cloud and managed service providers to navigate these challenges. In her session at Big Data Expo®, Hannah Smalltree, Director at Treasure Data, discussed how IoT, Big Data and deployments are processing massive data volumes from wearables, utilities and other machines...
Buzzword alert: Microservices and IoT at a DevOps conference? What could possibly go wrong? In this Power Panel at DevOps Summit, moderated by Jason Bloomberg, the leading expert on architecting agility for the enterprise and president of Intellyx, panelists will peel away the buzz and discuss the important architectural principles behind implementing IoT solutions for the enterprise. As remote IoT devices and sensors become increasingly intelligent, they become part of our distributed cloud environment, and we must architect and code accordingly. At the very least, you'll have no problem fil...
SYS-CON Events announced today that MetraTech, now part of Ericsson, has been named “Silver Sponsor” of SYS-CON's 16th International Cloud Expo®, which will take place on June 9–11, 2015, at the Javits Center in New York, NY. Ericsson is the driving force behind the Networked Society- a world leader in communications infrastructure, software and services. Some 40% of the world’s mobile traffic runs through networks Ericsson has supplied, serving more than 2.5 billion subscribers.
The 4th International Internet of @ThingsExpo, co-located with the 17th International Cloud Expo - to be held November 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA - announces that its Call for Papers is open. The Internet of Things (IoT) is the biggest idea since the creation of the Worldwide Web more than 20 years ago.
The worldwide cellular network will be the backbone of the future IoT, and the telecom industry is clamoring to get on board as more than just a data pipe. In his session at @ThingsExpo, Evan McGee, CTO of Ring Plus, Inc., discussed what service operators can offer that would benefit IoT entrepreneurs, inventors, and consumers. Evan McGee is the CTO of RingPlus, a leading innovative U.S. MVNO and wireless enabler. His focus is on combining web technologies with traditional telecom to create a new breed of unified communication that is easily accessible to the general consumer. With over a de...
Disruptive macro trends in technology are impacting and dramatically changing the "art of the possible" relative to supply chain management practices through the innovative use of IoT, cloud, machine learning and Big Data to enable connected ecosystems of engagement. Enterprise informatics can now move beyond point solutions that merely monitor the past and implement integrated enterprise fabrics that enable end-to-end supply chain visibility to improve customer service delivery and optimize supplier management. Learn about enterprise architecture strategies for designing connected systems tha...
Cloud is not a commodity. And no matter what you call it, computing doesn’t come out of the sky. It comes from physical hardware inside brick and mortar facilities connected by hundreds of miles of networking cable. And no two clouds are built the same way. SoftLayer gives you the highest performing cloud infrastructure available. One platform that takes data centers around the world that are full of the widest range of cloud computing options, and then integrates and automates everything. Join SoftLayer on June 9 at 16th Cloud Expo to learn about IBM Cloud's SoftLayer platform, explore se...
SYS-CON Media announced today that 9 out of 10 " most read" DevOps articles are published by @DevOpsSummit Blog. Launched in October 2014, @DevOpsSummit Blog offers top articles, news stories, and blog posts from the world's well-known experts and guarantees better exposure for its authors than any other publication. The widespread success of cloud computing is driving the DevOps revolution in enterprise IT. Now as never before, development teams must communicate and collaborate in a dynamic, 24/7/365 environment. There is no time to wait for long development cycles that produce softw...
With major technology companies and startups seriously embracing IoT strategies, now is the perfect time to attend @ThingsExpo in Silicon Valley. Learn what is going on, contribute to the discussions, and ensure that your enterprise is as "IoT-Ready" as it can be! Internet of @ThingsExpo, taking place Nov 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA, is co-located with 17th 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 an...
15th Cloud Expo, which took place Nov. 4-6, 2014, at the Santa Clara Convention Center in Santa Clara, CA, expanded the conference content of @ThingsExpo, Big Data Expo, and DevOps Summit to include two developer events. IBM held a Bluemix Developer Playground on November 5 and ElasticBox held a Hackathon on November 6. Both events took place on the expo floor. The Bluemix Developer Playground, for developers of all levels, highlighted the ease of use of Bluemix, its services and functionality and provide short-term introductory projects that developers can complete between sessions.
From telemedicine to smart cars, digital homes and industrial monitoring, the explosive growth of IoT has created exciting new business opportunities for real time calls and messaging. In his session at @ThingsExpo, Ivelin Ivanov, CEO and Co-Founder of Telestax, shared some of the new revenue sources that IoT created for Restcomm – the open source telephony platform from Telestax. Ivelin Ivanov is a technology entrepreneur who founded Mobicents, an Open Source VoIP Platform, to help create, deploy, and manage applications integrating voice, video and data. He is the co-founder of TeleStax, a...
The Internet of Things (IoT) promises to evolve the way the world does business; however, understanding how to apply it to your company can be a mystery. Most people struggle with understanding the potential business uses or tend to get caught up in the technology, resulting in solutions that fail to meet even minimum business goals. In his session at @ThingsExpo, Jesse Shiah, CEO / President / Co-Founder of AgilePoint Inc., showed what is needed to leverage the IoT to transform your business. He discussed opportunities and challenges ahead for the IoT from a market and technical point of vie...
Grow your business with enterprise wearable apps using SAP Platforms and Google Glass. SAP and Google just launched the SAP and Google Glass Challenge, an opportunity for you to innovate and develop the best Enterprise Wearable App using SAP Platforms and Google Glass and gain valuable market exposure. In his session at @ThingsExpo, Brian McPhail, Senior Director of Business Development, ISVs & Digital Commerce at SAP, outlined the timeline of the SAP Google Glass Challenge and the opportunity for developers, start-ups, and companies of all sizes to engage with SAP today.