Internationalizing Macromedia ColdFusion MX applications

beckonhissingInternet and Web Development

Nov 10, 2013 (3 years and 11 months ago)

95 views

Internationalizing Macromedia 
ColdFusion MX applications
 
A Macromedia ColdFusion application for an international user audience can incorporate several 
languages; the application can dynamically determine the language and numberic formatting to 
display to a user. To accept and render internationalized content correctly, an application requires 
appropriate locale variable, character sets, and character encodings. This article explains these 
elements, and how to use CFML tags and functions to specify the character encoding and language 
of input and output data in an application and a web browser. 
You can download example ColdFusion MX pages that show how to use the tags, functions, and 
options discussed in this article. 
Download the 
internationalization_cfmx.zip
file on any operating system. 
When the file decompresses, a folder named internationalization_example_pages is created on your 
system. 
If you have trouble downloading or decompressing the files, see TechNote 
13686

To display the example CFML code, open the example pages in a text editor or a ColdFusion editor 
such as Macromedia Dreamweaver MX. To execute the example CFML code, copy the files to an 
appropriate location and open the pages in a browser with ColdFusion MX server running. 
1. 
About locales 
2. 
Character encoding 
3. 
Internationalization tags and functions 
4. 
Internationalized application development tips 
5. 
Procedures and example code 
6. 
Information resources
 
1. 
About locales
 
The locale construct is a set of geographic, language, and variant variables that let an 
internationalized application dynamically determine how to process and format time and date values, 
currency values, and other elements in a way that is appropriate for a user. Locale settings control the 
punctuation and spacing of currency, time and date values, and the unit symbols used with the
m. 
Locale values also determine the character encoding that a web browser uses to render web content, 
such as ColdFusion pages. 
The following systems store separate locale values:
 
Windows operating system
 
The Windows locale variable value is determined by the Windows 
language version that is installed. The value determines, among other things, the language in which 
Windows menus display. You cannot change the value. Other operating systems use a similar 
mechanism.
System
 The system locale variable value 
is stored within a local computer. On Windows, its default 
value is the same as the operating system locale. The user can set its value. To change the system 
locale value, see 
Procedures and example code
.
 
Java default locale
 The Java default locale variable value determines the language and character 
encoding that Java uses. (ColdFusion MX executes most tags and functions 
in Java.) Its default value 
is the same as the system locale. The user can set its value. To change the Java default locale value, 
see 
Procedures and example code
.
 
2. Character encoding
 
Character encoding specifies mappings from a character set to the integer numbers that represent the 
characters on a computer. 
To read a CFM page, process information, and decode Form and URL variables, ColdFusion uses, by 
default, the character encoding specified by the Java default locale variable. 
For example, if the ColdFusion MX server computer's Java default locale is set to French(Standard), 
ColdFusion uses the character encoding for that locale, ISO­8859­1, to read pages and process 
information. I
t uses the UTF­8 character encoding for output. 
For each of these operations, you can override the character encoding default for a page, as the 
following sections explain.
 
Reading a ColdFusion page with a nondefault character encoding
 
Macromedia recommends that you encode all international application pages as UTF­8 with a byte­ 
order mark (BOM), so that ColdFusion automatically detects the page as UTF­8 encoded; no 
cfprocessingdirective 
tag is needed. The BOM sets the first byte of a UTF file, so the program reading 
the page recognizes which encoding is in use. 
If this is not possible, to specify that ColdFusion reads a page with a character encoding other than 
the Java default locale value, you use the cfprocessingdirective 
tag and pageencoding attribute, as 
follows: 
<cfprocessingdirective pageencoding=" 
encoding "> 
Typically, you assign one of the following values to 
encoding 

EUC­JP (Japanese) 
EUC­KR (Korean) 
ISO­8859­1 (Western European and English) 
SHIFT_JIS (Japanese) 
UTF­8 (All Languages)
If you save application pages in the default character encoding for your language, ColdFusion 
automatically reads them correctly. (This article assumes that the production ColdFusion server has 
the same Java default locale value as the computer on which you develop the application.) 
To cause the ColdFusion server to read a page in a different encoding, you use the 
cfprocessingdirective 
tag at the top of the page. For example, assume that the Java default locale is 
set to French. ColdFusion automatically reads and renders the page in French characters. To cause 
ColdFusion to read the page and render it in Japanese characters, you use the UTF
­8 encoding. The 
following code shows an example. 
You cannot propagate the effect of the cfprocessingdirective 
tag by putting it in an application.cfm 
page. You must add it to each page that has a nondefault encoding.
 
Generating ColdFusion page output with a nondefault character encoding
 
By default, ColdFusion MX uses the UTF­8 character encoding to render ColdFusion page output. 
With UTF­8 encoding, a browser receives page content as UTF­8 characters. 
To specify another output character encoding for the HTTP output of a page, including Form and URL 
variables, cookies, and cfmail tag content, you can us
e the cfcontent 
tag, as explained in this section. 
The cfcontent tag does not affect internal output such as data for a database, a file, or a ColdFusion 
variable; its function is unrelated to the 
cfprocessingdirective 
tag. 
The cfcontent tag syntax is as follows: 
<cfcontent type="text/html; charset= 
encoding 
"> 
You assign an encoding value to 
encoding 

If you put the 
cfcontent 
tag in an application.cfm file, its effects propagate throughout the application, 
overriding the ColdFusion default value.
 
Decoding HTTP Form and URL variables with a nondefault character encoding
 
By default, ColdFusion uses UTF­8 character encoding to decode and send Form and URL variables. 
By default, HTML does not process UTF­8 encoded data; its default is ISO­8859­1.
Because ASCII encoding is a subset of UTF­8, ColdFusion can process ASCII data automatically. To 
decode and send Form and URL variables in any other encoding (including the ColdFusion default 
character encoding), you must use the setEncoding 
function. Its syntax is as follows: 
setEncoding("_variable­
type_", " 
encoding 
") 
You assign an encoding value to 
encoding 

If you put a setEncoding 
function call in the application.cfm file, its effects propagate through the 
ColdFusion application. Alternatively
, put a setEncoding 
function call in the action page of each form 
that requires it. 
Set the encoding value as follows: 
If the form page has a cfcontent 
tag, set the encoding to the same value as the tag. 
If the form page does not have a 
cfcontent tag, set the encoding to UTF­8, regardless of the form page 
encoding. 
For each type of Form or URL variable that might contain non­ASCII data, put one setEncoding 
function call i
n the application.cfm or form page.
 
3. Internationalization tags and 
functions
 
The following table lists the tags and functions that have new internationalization functionality in 
ColdFusion MX.
 
Tags 
Functions
 
cfcontent 
setEncoding 
cffile (new 
charset attribute) 
setLocale 
cfhttp 
urlDecode 
cfprocessingdirective 
urlEncodedFormat 
For more information and examples, see 
CFML Reference 
and 
Developing ColdFusion MX 
Applications with CFML
.
 
Summary of character encoding scenarios
 
This section summarizes typical application setups and indicates which elements to use in each.
Setup 
Use setEncoding function 
Use 
cfprocessingdirecti 
ve tag 
Use cfcontent tag
 
All ColdFusion 
pages are 
encoded (saved) 
in UTF­8 with a 
BOM 
setEncoding("URL", "utf­8") and/or 
setEncoding("FORM", "utf
­8") 
No 
No 
All ColdFusion 
pages use the 
local computer's 
default operating 
system locale 
value 
setEncoding("URL", "utf­8") and/or 
setEncoding("FORM", "utf
­8") 
No 
No 
Some or all 
ColdFusion 
pages are saved 
in a nondefault 
character 
encoding 
("URL", "utf
­8") 
and/or 
setEncoding("FORM", "utf
­8") 
<cfprocessingdirective 
pageencoding= " 
page_encoding 
"> 
No 
Some or all 
ColdFusion 
pages are in 
default encoding 
but output should 
be in an encoding 
other than UTF­8 
setEncoding("URL", " 
output_encoding 
") 
and/or 
setEncoding("FORM", " 
output_encoding 
") 
No 
<cfcontent type= 
"text/html; charset= 
output_encoding 
"> 
Some or all 
ColdFusion 
pages are not in 
default encoding 
and output should 
be in an encoding 
other than UTF­8 
setEncoding("URL", " 
output_encoding 
") 
and/or 
setEncoding("FORM", " 
output_encoding 
") 
<cfprocessingdirective 
pageencoding= " 
page_encoding 
"> 
<cfcontent type= 
"text/html; charset= 
output_encoding 
"> 
In all setups, you use the setEncoding 
function only in the action page of a form or page that uses a 
Form or URL or Form variable. If your data is ASCII encoded and you do not use the cfcontent 
tag, it 
is not necessary to use the setEncoding function, regardless of the original page encoding.
 
4. Internationalized application 
development tips
 
This section provides suggestions for developers of internationalized applications.
 
Using UTF­8 and a BOM
 
Macromedia recommends that you use UTF­8 character encoding with ColdFusion MX. With this
encoding, the application can render all languages, regardless of locale values. ColdFusion MX 
automatically recognizes the BOM, so you do not use the cfprocessingdirective 
tag in your pages. 
The ColdFusion MX default output encoding for HTTP is UTF­8. 
Although it is probably not possible to completely migrate a ColdFusion 5 application to UTF­8, you 
should code new applications in UTF­8 because of its ease of use and simplicity. Macromedia 
Dreamweaver MX stores files as UTF­8 automatically and uses a BOM to mark them.
 
The setEncoding function and cfcontent tag in an application.cfm file
 
A simple way to migrate an application is to put setEncoding and cfcontent 
calls into the 
application.cfm file. This ensures that all pages function the same way and lets you avoid changing 
ColdFusion code. The effect of a cfprocessingdirective
tag on an Application.cfm file does not 
propagate through an application. You must add it to each file that has a different encoding than the 
default or that does not have a BOM.
 
Internationalizing database access
 
The following procedure explains how to set up a ColdFusion database to accept and process double­ 
byte data.
 
To use double­byte data with a MS Access database, you must do the following: 
1
 
On the server computer, run the batch file cfusionmx\db\sls
erver52
\admin\setcp.bat OS. (This file is installed 
with ColdFusion MX.)
 
2
 
Restart the ColdFusion MX ODBC Server. 
The DataDirect SequeLink Type III database drivers (ODBC Socket) that are used to connect to 
Microsoft Access databases do not support Unicode. The installed driver uses the operating system 
default character encoding.
 
CFX functions
 
To use CFX functionality with double­byte data, you must download and replace the cfxneo.dll file. 
This file will be available on the ColdFusion Support site in August, 2002; to locate it, search for an 
article with the filename.
 
Multipart POST
 
When submitting data through a form using the post 
method, if you use the 
form 
attribute value 
enctype= "multipart/form­data" 
, ColdFusion does not handle character encoding correctly. Instead, 
use code such as the following: 
<form action="#FOO#" 
method="post" 
enctype="multipart/form
­data: charset=utf
­8">
 
Included pages and custom tags
 
The cfprocessingdirective tag does not permit included pages and custom tags in the calling page. 
You must add the cfprocessingdirective 
tag to the included page.
Components
 
To output non­ASCII text from a component with the 
cfoutput tag, put a cfprocessingdirective 
tag 
within the 
cfcomponent 
tag. For an example of the 
cfprocessingdirective 
tag, see the code in 
Reading 
a ColdFusion page with a nondefault character encoding
.
 
Dates
 
ColdFusion MX uses Java standard date and time value formatting. In ColdFusion MX, you can use 
LS* functions (for example, LSCurrencyFormat) only with dates that are formatted in the Java 
standard for the current locale. To determine the correct format, use the now 
function to display a 
value. To ensure correct handling, create a date/time object for each v
alue. 
For more information on locales and ColdFusion MX, see Article 
9943
.
 
Verity
 
The Verity functions use the operating system default encoding. To use data that is in a language 
other than the operating system native language, you must encode in UTF­8. If the language is native 
to the operating system, use the operating system default encoding. For example, on a computer with 
Windows Japanese, to use Japanese data, encode in Shift_JIS; on a computer with Windows English, 
to use Japanese data, encode in UTF­8.
 
5. Procedures and example code
 
This section provides procedures to perform the tasks mentioned in this article and code examples.
 
To change the local computer's system locale value: 
1
 
In the Control Panel, select Regional Options.
 
2
 
In the General tab, determine whether the locale you want is selected. 
If so, go to the next step. 
If not, install the locale (select the locale and click Apply; the computer prompts for the Windows disk).
 
3
 
In the Regional Option window, in the General tab, select a locale. Click OK.
 
To change the local computer's Java default locale value:
 
To change the Java default locale value, do one of the following: 
Set the System Locale to the target value. 
Use command line parameters for the JVM. 
Temporarily change the locale with a Java method call ( Locale.setDefault(_locale_) ). 
To use command line parameters for the JVM, in the jvm.config file, add the following code to the end 
of the jvm.args line:
­Duser.language=<2­char­language­code> ­Duser.region=<2­char­country
­code> 
For example, to set language and country code to Japanese, use code such as the following: 
­Duser.language=ja ­Duser.region=JP 
To change 
only 
the ColdFusion MX Administrator display to match the browser language setting, use 
code such as the following in your Application.cfm file: 
<!
­­­ 
Use the request to get the client's preferred locale 
­­­> 
<cfset localize = getPageContext().getRequest().GetLocale()> 
<cfif not isDefined("localize")> 
<!
­­­ 
then use the default locale of the system we're running on ­­­

<cfset request.locale = 
createObject("java", "java.util.Locale").getDefault().getLanguage()> 
<cfelse> 
<cfset request.locale = localize.getLanguage()> 
</cfif> 
This does 
not 
change the LS* functions. This is a convenient way to change the language of the 
Administrator without restarting the ColdFusion server.
 
6. Information resources
 
For a list of the Java default locale values that ColdFusion MX supports, see the setLocale entry in 
CFML Reference

For more information about ColdFusion MX and operating system locale variables, and about 
formatting time, date, and currency values, see Article 
9943

For more information about character encoding, see the following: 
The Unicode Consortium website, 
Unicode definition page 
The World Wide Web Consortium website, 
International section
, which includes 

list of character sets 
The Internet Assigned Numbers Authority website, 
character set section