SetLocale  
Description
Sets the country/language locale for ColdFusion processing and the page returned to the client. The locale value determines the default format of date, time, number, and currency values, according to language and regional conventions.
 
Returns
The locale value prior to setting the new locale, as a string.
 
Category
International functions, System functions
 
Function syntax
SetLocale(new_locale)
 
See also
GetHttpTimeString, GetLocale
 
History
ColdFusion MX:
  • Changed formatting behavior: this function might return a different value than in earlier releases. This function uses Java standard locale determination and formatting rules on all platforms.
  • Deprecated the Spanish (Mexican) locale option. It might not work, and it might cause an error, in later releases.
  • Changed the Spanish (Modern) option: it now sets the locale to Spanish (Standard).
 
Parameters
 
Parameter      Description
new_locale The name of a locale; for example, "English (US)"
 
Usage
You can specify the following locale names:
Chinese (China) French (Belgian) Korean
Chinese (Hong Kong) French (Canadian) Norwegian (Bokmal)
Chinese (Taiwan) French (Standard) Norwegian (Nynorsk)
Dutch (Belgian) French (Swiss) Portuguese (Brazilian)
Dutch (Standard) German (Austrian) Portuguese (Standard)
English (Australian) German (Standard) Spanish (Modern)
English (Canadian) German (Swiss) Spanish (Standard)
English (New Zealand) Italian (Standard) Swedish
English (UK) Italian (Swiss)  
English (US) Japanese  
 
ColdFusion determines the locale value as follows:
  • By default, ColdFusion uses the JVM locale, and the default JVM locale is the operating system locale. You can set JVM locale value explicitly in ColdFusion MX in the ColdFusion Administrator Java and JVM Settings page JVM Arguments field; for example: -Duser.language=de -Duser.region=DE.
  • A locale set using the SetLocale function persists for the current request or until it is reset by another SetLocale function in the request.
  • If a request has multiple SetLocale functions, the current locale setting affects how locale-sensitive ColdFusion tags and functions, such as the functions that start with LS format data. The last SetLocale function that ColdFusion processes before sending a response to the requestor (typically the client browser) determines the value of the response Content-Language HTTP header. The browser that requested the page displays the response according to the rules for the language specified by the Content-Language header.
  • ColdFusion ignores any SetLocale functions that follow a cfflush tag.
Because this function returns the previous locale setting, you can save the original locale value. You can restore the original locale by calling SetLocale again with the saved variable. For example, the following line saves the original locale ins a Session variable:
<cfset Session.oldlocale = SetLocale(newLocale)>
The variable server.ColdFusion.SupportedLocales is initialized at startup with a comma-delimited list of the locales that ColdFusion and the operating system support. If you call SetLocale with a locale that is not in the list, the call generates an error.
Note: ColdFusion uses the Spanish (Standard) formats for Spanish (Modern) and Spanish (Standard).
 
Example
<h3>SetLocale Example</h3>
<p>SetLocale sets the locale to the specified new locale for the current 
session.
<p>A locale encapsulates the set of attributes that govern the display and
formatting of date, time, number, and currency values.
<p>The locale for this system is <cfoutput>#GetLocale()#</cfoutput>
<p><cfoutput><I>the old locale was #SetLocale("English (UK)")#</I>
<p>The locale is now #GetLocale()#</cfoutput>
new_locale  
The name of a locale; for example, "English (US)"