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, GetLocaleDisplayName; "Locales" in the ColdFusion Developer's Guide

History

ColdFusion MX 7: Added support for all locales supported by the ColdFusion Java runtime.

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

Usage

You can specify any locale name that is listed in the Server.Coldfusion.SupportedLocales variable. This variable is a comma-delimited list of all locale names supported by the JVM, plus the locale names that were required by ColdFusion prior to ColdFusion MX 7.

The following locale names were used in ColdFusion releases through ColdFusion MX 6.1, and continue to be supported. If you use any of these values in the SetLocale function, the GetLocale function returns the name you set, not the corresponding Java locale name.

ColdFusion determines the locale value as follows:

1. 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 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.

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>